dsh-search-enhance 0.1.0 → 0.1.2

package/README.md

@@ -12,47 +12,51 @@
   ▼
 DSH Agent
   │
-  ├─ web_search ──────> Grok 主搜索
-  │                      ├─ 按需要补充 Context7 / Exa
-  │                      ├─ 按需要补充 Tavily / Firecrawl
-  │                      └─ 返回回答、来源，必要时返回 source_ref
-  │
-  ├─ docs_search ─────> Context7 / Exa 文档检索
-  │                      └─ 返回文档片段、来源，必要时返回 source_ref
-  │
-  ├─ web_extract ─────> Tavily → Firecrawl → smart_direct → direct
-  │                      └─ 读取选中网页的正文
-  │
-  └─ search_tools ────> 按需开放更多工具
-                         ├─ Context7 精细查询
-                         ├─ 完整来源分页
-                         ├─ 站点页面发现
-                         ├─ 研究计划
-                         └─ 配置诊断
+  └─ 固定模型工具 surface（schema 与顺序不随披露状态变化）
+      ├─ web_search ──────> Grok 主搜索
+      │                      ├─ 按需要补充 Context7 / Exa
+      │                      ├─ 按需要补充 Tavily / Firecrawl
+      │                      └─ 返回回答、来源；有 source_ref 时追加 search_sources manifest
+      │
+      ├─ docs_search ─────> Context7 / Exa 文档检索
+      │                      └─ 返回文档片段、来源；有 source_ref 时追加 search_sources manifest
+      │
+      ├─ web_extract ─────> Tavily → Firecrawl → smart_direct → direct
+      │                      └─ 读取选中网页的正文
+      │
+      ├─ search_tools ────> 按需返回 capability / operation manifest
+      │
+      └─ search_call ─────> 调用已经激活的延迟 operation
+                             ├─ Context7 精细查询
+                             ├─ 完整来源分页
+                             ├─ 站点页面发现
+                             ├─ 研究计划
+                             └─ 配置诊断
 ```
 
 插件继续使用 DSH 原有的 `web_search` 名称，不会再增加第二个普通搜索入口。在本来可以使用 `web_search` 的 Agent 中，插件提供增强后的搜索；如果某个 Agent 已经禁用网页搜索，插件不会强行重新开启。
 
 普通搜索以 Grok 为主。其他服务只负责补充文档、来源或网页内容，不会替代 Grok 的主搜索位置。
 
-### 初始可用工具
+### 固定模型工具 surface
 
-默认使用渐进式披露。每个新 Agent 开始时，插件提供的搜索工具中只显示以下四个：
+默认使用 `progressive`。在 DSH 未另行限制的 Agent 中，插件在初始步骤和后续步骤提供的五个固定搜索入口（Native tool / Code Mode SDK）是：
 
-| 工具 | 用途 |
+| 工具 | 调用方式与用途 |
 | --- | --- |
-| `web_search` | 通用搜索。使用 Grok 生成主要回答，并按搜索类型补充其他来源 |
-| `docs_search` | 面向库、框架、SDK、API 和源码仓库的文档检索 |
-| `web_extract` | 读取指定网页正文，用于核对搜索摘要中的重要内容 |
-| `search_tools` | 当前四个工具不足时，按需要开放后续工具 |
+| `web_search` | 直接调用。使用 Grok 生成通用搜索的主要回答，并按搜索类型补充其他来源 |
+| `docs_search` | 直接调用。检索库、框架、SDK、API 和源码仓库文档 |
+| `web_extract` | 直接调用。读取指定网页正文，用于核对搜索摘要中的重要内容 |
+| `search_tools` | 直接调用。按需返回延迟能力的 operation manifest，不注册新的模型工具 |
+| `search_call` | 固定网关。通过 `search_call({ operation, arguments })` 调用已经激活的延迟 operation |
 
-这样可以避免一开始向模型展示全部工具，同时保留深度搜索所需的完整能力。
+这里的“延迟”指 operation 是否处于 active 状态，而不是工具是否出现在列表中。延迟 operation 的参数 schema 通过工具结果中的 manifest 披露；输出 schema 只保存在内部 registry，用于校验规范执行结果，不会追加到模型历史，也不会作为独立工具加入模型 surface。
 
 ### 渐进式披露
 
 `search_tools` 一次可以选择一到五组能力：
 
-| 能力组 | 开放的工具 | 适用场景 |
+| 能力组 | 按需返回 manifest 的 operation | 适用场景 |
 | --- | --- | --- |
 | `context7` | `context7_resolve_library_id`、`context7_query_docs`、`context7_get_library_docs`、`context7_get_cached_doc_raw` | 需要精确选择库版本或进一步读取 Context7 文档 |
 | `sources` | `search_sources` | 搜索结果中的来源较多，需要继续分页读取完整来源 |
@@ -60,23 +64,24 @@ DSH Agent
 | `planning` | `research_plan` | 明确要求深度研究、多来源核对或复杂比较时先制定计划 |
 | `diagnostics` | `search_diagnostics` | 用户明确要求检查搜索配置或连接状态 |
 
-渐进式披露遵循以下规则：
+披露与调用遵循以下规则：
 
-1. 新工具不会在 `search_tools` 调用的同一步立即出现，而会从下一步开始可用。
-2. 开放范围只属于当前 Agent；已经开放的能力会保留，重复开放不会产生第二套工具。
-3. `web_search` 或 `docs_search` 成功返回 `source_ref` 后，`sources` 会自动开放，不需要再次调用 `search_tools`。
-4. 插件只会减少自己设置的隐藏范围，不能绕过 DSH 原有的工具限制。
-5. 不应预先开放全部能力；只有初始四个工具无法完成任务时才按需增加。
+1. `search_tools` 返回所请求能力组的 operation manifest，其中包含真实的参数 schema 和 `search_call` 路由，但不包含内部输出 schema；它不会增加、删除或改写模型工具 schema。`search_call` 仍使用 registry 保存的输出 schema 校验规范结果。
+2. 在 `progressive` 模式下，新披露的能力组从下一模型 step 开始 active；同一步内提前调用会失败。激活范围属于当前 Agent，重复请求会再次返回同一 manifest，但不会创建第二套状态或入口。
+3. 在 `all` 模式下，唯一变化是所有延迟 operation 从一开始就 active；`search_tools` 仍按需返回 manifest。`all` 不会“显示全部 12 个工具”，两种模式的五个模型工具及其 schema 完全相同。
+4. 延迟 operation 只能通过 `search_call({ operation, arguments })` 调用，不能直接调用 `search_sources`、`web_map` 等名称；resident 的 `web_search`、`docs_search` 和 `web_extract` 仍然直接调用。
+5. `web_search` 或 `docs_search` 成功返回 `source_ref` 时，插件会自动激活 `sources`，并在结果中追加 `search_sources` manifest；在 `progressive` 模式下可从下一 step 通过 `search_call` 使用它。
+6. 固定 surface 仍受 DSH 原有 Preset、guard 和工具限制约束，插件不会绕过这些限制。
 
-如果希望插件一开始就显示全部 12 个工具，可以在配置页把“工具披露模式”改为 `all`。默认的 `progressive` 更适合普通使用；无论选择哪种模式，DSH 原有的工具限制仍然有效。
+这种固定网关设计保留了按需披露，同时避免插件因披露状态变化而改写发送给 DeepSeek 的 system 文本、tool schema/顺序或 Code Mode SDK 前缀，从而消除插件自身造成的前缀变化。
 
 ### 一次完整搜索如何进行
 
-1. 通用问题先使用 `web_search`，文档问题优先使用 `docs_search`。
-2. 当搜索产生来源时，会同时返回可见来源和一个可继续读取完整来源的 `source_ref`。
-3. 需要更多来源时使用自动开放的 `search_sources` 分页读取。
-4. 对重要结论，选择权威链接并使用 `web_extract` 获取网页正文。
-5. 如果任务需要站点内发现、研究计划或连接检查，再通过 `search_tools` 开放对应能力。
+1. 通用问题直接调用 `web_search`，文档问题直接调用 `docs_search`。
+2. 当搜索产生来源时，结果会包含可见来源、`source_ref` 和追加的 `search_sources` manifest，同时自动激活 `sources`。
+3. 在下一 step 需要更多来源时，调用 `search_call({ operation: 'search_sources', arguments: { source_ref, offset: 0, limit: 20, format: 'compact' } })` 分页读取，而不是直接调用 `search_sources`。
+4. 对重要结论，选择权威链接并直接调用 `web_extract` 获取网页正文。
+5. 如果任务需要站点内发现、研究计划、精细 Context7 查询或连接检查，先调用例如 `search_tools({ capabilities: ['site_map'] })` 取得 manifest；`progressive` 模式从下一 step、`all` 模式立即通过 `search_call({ operation: 'web_map', arguments: { url: 'https://example.com' } })` 调用相应 operation。
 6. 最终回答综合主搜索、补充来源和已经读取的网页正文，并保留来源链接。
 
 `source_ref` 只是完整来源列表的引用，不等同于网页正文；重要事实仍应通过 `web_extract` 读取原页面后再下结论。
@@ -147,7 +152,7 @@ dsh web
 
 不确定时保持默认值即可，也可以在单次搜索中临时选择其他设置。
 
-“工具披露模式”建议保持 `progressive`，让工具按任务需要逐步出现；只有明确希望一开始显示全部搜索工具时才选择 `all`。
+“工具披露模式”建议保持 `progressive`，让延迟 operation 按需披露并从下一模型 step 激活；`all` 只让所有延迟 operation 从一开始处于 active 状态。两种模式都保留同一组五个模型工具及相同 schema，不会显示额外的独立工具。
 
 ### 4. 配置网页代理
 
@@ -210,9 +215,3 @@ dsh plugin --profile web add dsh-search-enhance@latest
 ```bash
 dsh plugin --profile web remove dsh-search-enhance
 ```
-
-## 使用提示
-
-- 网页正文读取不会执行页面 JavaScript，也不能处理登录、验证码或浏览器会话。
-- 网页读取可以访问 DSH 所在机器能够访问的地址；在敏感网络中只处理可信链接，并配合网络访问限制。
-- 如果配置页面没有出现，先用 `dsh plugin --profile web list --depth 0` 确认 npm 包已经安装，然后重启 DSH 并强制刷新浏览器。

package/lib/config.d.ts

@@ -8,7 +8,7 @@ export type SearchDepth = (typeof SEARCH_DEPTHS)[number];
 export declare const TOOL_DISCOVERY_MODES: readonly ["progressive", "all"];
 export type ToolDiscoveryMode = (typeof TOOL_DISCOVERY_MODES)[number];
 export interface ToolDiscoveryConfig {
-    /** progressive applies per-Agent disclosure; all installs no plugin restriction. */
+    /** progressive gates deferred operations per Agent; all activates every operation. */
     readonly mode: ToolDiscoveryMode;
 }
 /** Stable high-level docs_search default; the Settings cap is independently bounded. */

package/lib/index.js

@@ -14,8 +14,8 @@ 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, isDeferredToolName, } from './tool-discovery/index.js';
-import { ForegroundOperationScope, createContext7Tools, createDocsSearchTool, createWebSearchTool, createResearchPlanTool, createSearchDiagnosticsTool, createSearchSourcesTool, createSearchToolsTool, createWebExtractTool, createWebMapTool, } from './tools/index.js';
+import { foldEffectiveToolDisclosureEvents, installAgentToolDisclosure, } from './tool-discovery/index.js';
+import { ForegroundOperationScope, DeferredOperationRegistry, createContext7Tools, createDocsSearchTool, createResearchPlanTool, createSearchCallTool, createSearchDiagnosticsTool, createSearchSourcesTool, createSearchToolsTool, createWebExtractTool, createWebMapTool, createWebSearchTool, } from './tools/index.js';
 import { WebExtractOrchestrator } from './web-extract/orchestrator.js';
 import { installWebConfigBridge } from './web-config/host.js';
 export const name = 'search-enhance';
@@ -94,25 +94,12 @@ export async function apply(ctx, config) {
         direct: new DirectFetchProvider(),
         getConfig,
     });
-    const webSearchDefinition = createWebSearchTool({
-        getConfig,
-        operations,
-        orchestrator,
-        sources: ctx.searchEnhanceSources,
-    });
-    const globalToolDefinitions = [
-        createDocsSearchTool({
+    const deferredOperationDefinitions = [
+        ...createContext7Tools({
             documentation,
             getConfig,
             operations,
-            sources: ctx.searchEnhanceSources,
-        }),
-        createWebExtractTool({
-            getConfig,
-            operations,
-            orchestrator: webExtract,
         }),
-        createSearchToolsTool({ mode: effective.toolDiscovery.mode }),
         createSearchSourcesTool({
             getConfig,
             operations,
@@ -125,7 +112,9 @@ export async function apply(ctx, config) {
         }),
         createResearchPlanTool({
             getConfig,
-            isWebMapAvailable: agent => ctx.tools.get('web_map', agent) !== undefined,
+            isWebMapAvailable: agent => agent !== undefined && (effective.toolDiscovery.mode === 'all'
+                || foldEffectiveToolDisclosureEvents(agent.session.events).activeGroups
+                    .includes('site_map')),
             operations,
         }),
         createSearchDiagnosticsTool({
@@ -133,22 +122,42 @@ export async function apply(ctx, config) {
             operations,
             reporter: diagnostics,
         }),
-        ...createContext7Tools({
+    ];
+    const deferredOperations = new DeferredOperationRegistry(deferredOperationDefinitions);
+    const sourceOperationNotice = deferredOperations.renderCapabilityDisclosure('sources');
+    const webSearchDefinition = createWebSearchTool({
+        getConfig,
+        operations,
+        orchestrator,
+        sourceOperationNotice,
+        sources: ctx.searchEnhanceSources,
+    });
+    const residentToolDefinitions = [
+        createDocsSearchTool({
             documentation,
             getConfig,
             operations,
+            sourceOperationNotice,
+            sources: ctx.searchEnhanceSources,
+        }),
+        createWebExtractTool({
+            getConfig,
+            operations,
+            orchestrator: webExtract,
+        }),
+        createSearchToolsTool({
+            mode: effective.toolDiscovery.mode,
+            registry: deferredOperations,
+        }),
+        createSearchCallTool({
+            mode: effective.toolDiscovery.mode,
+            registry: deferredOperations,
         }),
     ];
-    for (const definition of globalToolDefinitions)
+    for (const definition of residentToolDefinitions)
         ctx.tools.register(definition);
-    installAgentToolDisclosure(ctx, {
-        mode: effective.toolDiscovery.mode,
-        deferredToolNames: globalToolDefinitions
-            .map(definition => definition.name)
-            .filter(isDeferredToolName),
-        webSearchDefinition,
-    });
-    registerToolDiscoveryGuidance(ctx, effective.toolDiscovery.mode);
+    installAgentToolDisclosure(ctx, { webSearchDefinition });
+    registerToolDiscoveryGuidance(ctx);
     installWebConfigBridge(ctx);
 }
 //# sourceMappingURL=index.js.map

package/lib/presentation/render.d.ts

@@ -4,9 +4,9 @@ import type { DocsSearchOutput, WebSearchOutput, SearchDiagnosticsOutput, Search
  * limit is carried in the canonical value, so replay never consults Settings,
  * a cache, the clock, or network state.
  */
-export declare function renderWebSearchText(value: WebSearchOutput): string;
+export declare function renderWebSearchText(value: WebSearchOutput, sourceOperationNotice?: string): string;
 /** 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 renderDocsSearchText(value: DocsSearchOutput, sourceOperationNotice?: string): string;
 /** Pure model-text projection for one private-storage source page. */
 export declare function renderSearchSourcesText(value: SearchSourcesOutput): string;
 /**

package/lib/presentation/render.js

@@ -3,6 +3,37 @@ const DISCOVERY_NOTICE = 'Evidence level: discovery. Snippets are discovery meta
 function inline(value) {
     return value.replace(/\s+/gu, ' ').trim();
 }
+function renderWithBoundedNotice(text, notice, maximumBytes, fallbackNotice) {
+    if (notice === undefined || notice.length === 0) {
+        return truncateUtf8(text, maximumBytes).text;
+    }
+    const separator = '\n\n';
+    const complete = `${text}${separator}${notice}`;
+    if (utf8ByteLength(complete) <= maximumBytes)
+        return complete;
+    const noticeBytes = utf8ByteLength(notice);
+    if (noticeBytes > maximumBytes) {
+        // Never expose a partial JSON capability manifest. A short plain-text
+        // fallback can still point the model at the durable source reference.
+        return truncateUtf8(fallbackNotice ?? notice, maximumBytes).text;
+    }
+    const prefixBudget = maximumBytes - noticeBytes - utf8ByteLength(separator);
+    if (prefixBudget <= 0)
+        return notice;
+    const prefix = truncateUtf8(text, prefixBudget).text;
+    return prefix.length === 0 ? notice : `${prefix}${separator}${notice}`;
+}
+function sourceDisclosureTail(sourceRef, operationNotice) {
+    if (sourceRef === undefined)
+        return undefined;
+    return [
+        `Source reference: ${sourceRef}`,
+        operationNotice,
+    ].filter((line) => line !== undefined && line.length > 0).join('\n\n');
+}
+function sourceDisclosureFallback(sourceRef) {
+    return `Source reference: ${sourceRef}\n\nCall search_tools({ capabilities: ["sources"] }) to retrieve the search_sources manifest.`;
+}
 function warningText(warning) {
     const subject = [warning.provider, warning.capability].filter(Boolean).join('/');
     const suffix = [subject, warning.error_kind].filter(Boolean).join(', ');
@@ -58,11 +89,7 @@ function sourceSection(value) {
     return lines.join('\n');
 }
 function sourceSummary(value) {
-    const lines = [`Sources shown: ${value.returned_sources}/${value.total_sources}`];
-    if (value.source_ref !== undefined) {
-        lines.push(`Source reference: ${value.source_ref}`);
-    }
-    return lines.join('\n');
+    return `Sources shown: ${value.returned_sources}/${value.total_sources}`;
 }
 function limitationsSection(value) {
     const lines = [];
@@ -80,7 +107,7 @@ function limitationsSection(value) {
  * limit is carried in the canonical value, so replay never consults Settings,
  * a cache, the clock, or network state.
  */
-export function renderWebSearchText(value) {
+export function renderWebSearchText(value, sourceOperationNotice) {
     const sections = [
         answerSection(value),
         sourceSection(value),
@@ -93,7 +120,7 @@ export function renderWebSearchText(value) {
         && value.model_text_max_bytes > 0
         ? value.model_text_max_bytes
         : 0;
-    return truncateUtf8(complete, maximumBytes).text;
+    return renderWithBoundedNotice(complete, sourceDisclosureTail(value.source_ref, sourceOperationNotice), maximumBytes, value.source_ref === undefined ? undefined : sourceDisclosureFallback(value.source_ref));
 }
 function docsWarningText(warning) {
     const subject = [warning.provider, warning.path].filter(Boolean).join('/');
@@ -173,7 +200,7 @@ function docsSourceSection(value) {
     return lines.join('\n');
 }
 /** Pure Native projection for docs_search; it never reads Settings, cache, storage, or the network. */
-export function renderDocsSearchText(value) {
+export function renderDocsSearchText(value, sourceOperationNotice) {
     const status = value.state === 'partial' ? 'partial' : 'complete';
     const explanation = value.state === 'partial'
         ? 'Some documentation paths failed or stale cache data was used; available discovery results follow.'
@@ -188,8 +215,7 @@ export function renderDocsSearchText(value) {
         [
             `Sources shown: ${value.returned_sources}/${value.total_sources}`,
             `Snippets shown: ${value.returned_snippets}/${value.total_snippets}`,
-            value.source_ref === undefined ? undefined : `Source reference: ${value.source_ref}`,
-        ].filter((line) => line !== undefined).join('\n'),
+        ].join('\n'),
         [
             docsCachePathText('Context7 resolve cache', value.cache.resolve),
             docsCachePathText('Context7 docs cache', value.cache.docs),
@@ -211,7 +237,7 @@ export function renderDocsSearchText(value) {
         && value.model_text_max_bytes > 0
         ? value.model_text_max_bytes
         : 0;
-    return truncateUtf8(complete, maximumBytes).text;
+    return renderWithBoundedNotice(complete, sourceDisclosureTail(value.source_ref, sourceOperationNotice), maximumBytes, value.source_ref === undefined ? undefined : sourceDisclosureFallback(value.source_ref));
 }
 function renderPageSources(page) {
     if (page.sources.length === 0)
@@ -490,7 +516,7 @@ function completeSearchDiagnosticsText(value) {
         `Search API protocol: ${value.configuration.search_api_protocol}`,
         `Search model configured: ${value.configuration.search_model_configured}`,
         `Thinking/fallback: ${value.configuration.thinking_level}/${value.configuration.fallback_mode}`,
-        `Plugin definitions: web_map=${value.configuration.web_map_enabled}, research_plan=${value.configuration.research_plan_enabled}, diagnostics=${value.configuration.diagnostics_enabled} (final Agent visibility may be further restricted)`,
+        `Configured deferred operations: web_map=${value.configuration.web_map_enabled}, research_plan=${value.configuration.research_plan_enabled}, diagnostics=${value.configuration.diagnostics_enabled} (invoke active operations through search_call)`,
         `Search routes enabled: tavily=${value.configuration.tavily_search_enabled}, firecrawl=${value.configuration.firecrawl_search_enabled}`,
         `Extract routes enabled: tavily=${value.configuration.tavily_extract_enabled}, firecrawl=${value.configuration.firecrawl_scrape_enabled}, smart_direct=${value.configuration.smart_direct_enabled}, direct=${value.configuration.direct_enabled}`,
     ].join('\n');

package/lib/prompt/tool-discovery.d.ts

@@ -1,5 +1,6 @@
 import type { Context } from '@deepseek-ai/cordis';
-import type { ToolDiscoveryMode } from '../config.js';
-/** Register scope-aware disclosure and evidence guidance for Search Enhance tools. */
-export declare function registerToolDiscoveryGuidance(ctx: Context, mode: ToolDiscoveryMode): void;
+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. */
+export declare function registerToolDiscoveryGuidance(ctx: Context): void;
 //# sourceMappingURL=tool-discovery.d.ts.map

package/lib/prompt/tool-discovery.js

@@ -1,49 +1,26 @@
-import { CAPABILITY_GROUPS } from '../tool-discovery/capabilities.js';
-import { foldToolDisclosureEvents } from '../tool-discovery/fold.js';
-const EVIDENCE_DISCOVERY_TOOLS = ['web_search', 'docs_search'];
-function evidenceDisciplineText(visibleDiscoveryTools, webExtractVisible) {
-    if (visibleDiscoveryTools.length === 0)
-        return '';
-    const route = visibleDiscoveryTools.length === 2
-        ? '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.'
-        : visibleDiscoveryTools[0] === 'web_search'
-            ? 'For current or external factual questions, start with one focused web_search; do not inspect local files, settings, sessions, or credentials unless the user explicitly asks about local state.'
-            : 'For current or external SDK/API documentation questions, start with one focused docs_search; do not inspect local files, settings, sessions, or credentials unless the user explicitly asks about local state.';
-    return [
-        route,
-        `Treat ${visibleDiscoveryTools.join('/')} answers, snippets, and source metadata as discovery, not claim-level evidence.`,
-        webExtractVisible
-            ? '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.'
-            : 'Never present an inferred mechanism as source-stated fact; label unestablished mechanisms as inference or unconfirmed.',
-    ].join('\n');
-}
-/** Register scope-aware disclosure and evidence guidance for Search Enhance tools. */
-export function registerToolDiscoveryGuidance(ctx, mode) {
+export const TOOL_DISCOVERY_GUIDANCE = [
+    'Search Enhance keeps a fixed model-facing surface: web_search, docs_search, web_extract, search_tools, and search_call.',
+    'Use search_tools only when the resident search tools cannot complete the task. It returns append-only capability and operation manifests; do not activate every capability preemptively.',
+    'Run a manifested deferred operation with search_call({ operation, arguments }). In progressive mode, a newly disclosed capability is callable on the next model step; in all mode, deferred operations are active immediately. search_call fails closed while an operation is inactive.',
+    'Activate planning only for explicit deep research, multi-source verification, or complex comparison. Activate diagnostics only when the user asks about Provider configuration or connectivity.',
+    'A successful web_search or docs_search result with source_ref activates the sources capability. Use the appended search_sources manifest, or call search_tools for sources to replay that manifest before search_call.',
+].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.',
+].join('\n');
+/** Register deterministic guidance that never reads Agent state or tool visibility. */
+export function registerToolDiscoveryGuidance(ctx) {
     ctx.systemPrompt.section({
         name: 'search-enhance:tool-discovery',
         order: 121,
-        text: context => {
-            if (mode === 'all'
-                || context.agent === undefined
-                || ctx.tools.get('search_tools', context.scope) === undefined)
-                return '';
-            const active = new Set(foldToolDisclosureEvents(context.agent.session.events).activeGroups);
-            const remaining = CAPABILITY_GROUPS.filter(group => !active.has(group));
-            if (remaining.length === 0)
-                return '';
-            return [
-                `Additional Search Enhance capabilities are deferred for this Agent: ${remaining.join(', ')}.`,
-                'Use search_tools only when web_search, docs_search, and web_extract cannot complete the task; do not activate every group preemptively.',
-                'Activate planning only for explicit deep research, multi-source verification, or complex comparison. Activate diagnostics only when the user asks about Provider configuration or connectivity.',
-                'A successful disclosure applies on the next model step and cannot bypass another Preset restriction. In Code Mode, call search_tools through the current run_code SDK and wait for the next step before using newly disclosed bindings.',
-                'Successful source-producing searches disclose sources automatically, so do not request it again when already active.',
-            ].join('\n');
-        },
+        text: TOOL_DISCOVERY_GUIDANCE,
     });
     ctx.systemPrompt.section({
         name: 'search-enhance:evidence-discipline',
         order: 122,
-        text: context => evidenceDisciplineText(EVIDENCE_DISCOVERY_TOOLS.filter(tool => ctx.tools.get(tool, context.scope) !== undefined), ctx.tools.get('web_extract', context.scope) !== undefined),
+        text: EVIDENCE_DISCIPLINE_GUIDANCE,
     });
 }
 //# sourceMappingURL=tool-discovery.js.map

package/lib/providers/direct-fetch.d.ts

@@ -9,8 +9,10 @@ export interface DirectFetchProviderDependencies extends DirectHttpDependencies
 /**
  * Production `direct` route. It performs bounded Node HTTP(S) requests without
  * JavaScript, cookies, login flows, CAPTCHA handling, browser emulation, or any
- * destination-network classification. Localhost, private, metadata, reserved,
- * and DNS-rebinding targets are deliberately not blocked by this adapter.
+ * destination-network classification. Recognizable anti-bot interstitials are
+ * unavailable rather than returned as direct page evidence. Localhost, private,
+ * metadata, reserved, and DNS-rebinding targets are deliberately not blocked
+ * by this adapter.
  */
 export declare class DirectFetchProvider implements WebExtractAdapter {
     readonly route: "direct";

package/lib/providers/direct-fetch.js

@@ -1,5 +1,6 @@
 import { abortableDelay, exponentialBackoffMs, isProviderError, ProviderError, runWithTimeout, throwIfAborted, } from '../provider-runtime/index.js';
 import { normalizeWebExtractUrl } from '../web-extract/url.js';
+import { isLikelyAntiBotChallenge } from './web-extract-common.js';
 import { isWebExtractFormat } from '../web-extract/types.js';
 import { inspectDirectHtml, projectDirectContent, } from './direct-content.js';
 import { fetchDirectHttpHop, } from './direct-http.js';
@@ -35,8 +36,10 @@ function delayForRetry(failedRetryNumber, error, policy, random) {
 /**
  * Production `direct` route. It performs bounded Node HTTP(S) requests without
  * JavaScript, cookies, login flows, CAPTCHA handling, browser emulation, or any
- * destination-network classification. Localhost, private, metadata, reserved,
- * and DNS-rebinding targets are deliberately not blocked by this adapter.
+ * destination-network classification. Recognizable anti-bot interstitials are
+ * unavailable rather than returned as direct page evidence. Localhost, private,
+ * metadata, reserved, and DNS-rebinding targets are deliberately not blocked
+ * by this adapter.
  */
 export class DirectFetchProvider {
     route = PROVIDER;
@@ -89,6 +92,9 @@ export class DirectFetchProvider {
             }
             const contentInput = this.contentInput(response, input);
             const inspection = inspectDirectHtml(contentInput);
+            if (isLikelyAntiBotChallenge(inspection.scanText, response.statusCode)) {
+                throw new ProviderError({ capability: CAPABILITY, kind: 'unavailable', provider: PROVIDER });
+            }
             const navigationTarget = inspection.metaRefreshUrl ?? inspection.alternateUrl;
             if (navigationTarget !== undefined) {
                 target = this.nextTarget(navigationTarget, response.url, input.config.webExtract.maxUrlCharacters, directConfig.maxRedirects, seen, budget);

package/lib/providers/direct-http.js

@@ -5,6 +5,7 @@ import { pipeline } from 'node:stream/promises';
 import { createBrotliDecompress, createGunzip, createInflate, } from 'node:zlib';
 import { isProviderError, parseRetryAfterMs, ProviderError, providerHttpError, RETRYABLE_HTTP_STATUSES, throwIfAborted, } from '../provider-runtime/index.js';
 import { isDirectTextLikeContentType, } from './direct-content.js';
+import { isLikelyAntiBotChallenge } from './web-extract-common.js';
 const PROVIDER = 'direct';
 const CAPABILITY = 'web_extract';
 const HTTP_REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
@@ -468,6 +469,9 @@ export async function fetchDirectHttpHop(input, dependencies = {}) {
         if (input.config.proxyUrl !== undefined && statusCode === 407) {
             throw providerHttpError({ capability: CAPABILITY, provider: PROVIDER, status: statusCode });
         }
+        if (isLikelyAntiBotChallenge('', statusCode, scalarHeader(response, 'cf-mitigated'))) {
+            throw new ProviderError({ capability: CAPABILITY, kind: 'unavailable', provider: PROVIDER });
+        }
         const contentType = scalarHeader(response, 'content-type');
         const contentLength = parseContentLength(scalarHeader(response, 'content-length'));
         const contentDisposition = scalarHeader(response, 'content-disposition');

package/lib/providers/firecrawl-scrape.d.ts

@@ -11,7 +11,9 @@ export interface FirecrawlScrapeProviderDependencies extends ProviderHttpDepende
 export declare function firecrawlFormatForWebExtract(format: WebExtractFormat): FirecrawlFormat | undefined;
 /**
  * Parse one Firecrawl v2 scrape envelope. The requested format is selected from
- * `data[format]`; `metadata` is projected only for explicit scalar fields.
+ * `data[format]`; recognizable anti-bot challenge content throws a fixed
+ * unavailable error instead of consuming empty-content retries, and `metadata`
+ * is projected only for explicit scalar fields.
  */
 export declare function parseFirecrawlScrapeResponse(body: string, format: Extract<WebExtractFormat, 'markdown' | 'html' | 'raw'>, maximumUrlCharacters: number, maximumContentCharacters: number): WebExtractAdapterResult | undefined;
 /** Registration-free Firecrawl v2 `POST /scrape` adapter. */

package/lib/providers/firecrawl-scrape.js

@@ -1,4 +1,4 @@
-import { boundedExtractedContent, remoteMetadata, responseRecord, } from './web-extract-common.js';
+import { boundedExtractedContent, isLikelyAntiBotChallenge, remoteMetadata, responseRecord, } from './web-extract-common.js';
 import { parseProviderJson, providerEndpoint, resolveOptionalCredential, } from './helpers.js';
 import { ProviderError, throwIfAborted, } from '../provider-runtime/index.js';
 import { ProviderHttpClient, } from './http.js';
@@ -15,7 +15,9 @@ export function firecrawlFormatForWebExtract(format) {
 }
 /**
  * Parse one Firecrawl v2 scrape envelope. The requested format is selected from
- * `data[format]`; `metadata` is projected only for explicit scalar fields.
+ * `data[format]`; recognizable anti-bot challenge content throws a fixed
+ * unavailable error instead of consuming empty-content retries, and `metadata`
+ * is projected only for explicit scalar fields.
  */
 export function parseFirecrawlScrapeResponse(body, format, maximumUrlCharacters, maximumContentCharacters) {
     const root = responseRecord(parseProviderJson(body, PROVIDER, CAPABILITY), PROVIDER);
@@ -31,14 +33,19 @@ export function parseFirecrawlScrapeResponse(body, format, maximumUrlCharacters,
     if (firecrawlFormat === undefined)
         return undefined;
     const data = root.data;
-    const content = boundedExtractedContent(data[firecrawlFormat], maximumContentCharacters);
+    const metadata = remoteMetadata(isRecord(data.metadata) ? data.metadata : undefined, maximumUrlCharacters);
+    const extracted = data[firecrawlFormat];
+    if (typeof extracted === 'string'
+        && isLikelyAntiBotChallenge(extracted, metadata.statusCode)) {
+        throw new ProviderError({ capability: CAPABILITY, kind: 'unavailable', provider: PROVIDER });
+    }
+    const content = boundedExtractedContent(extracted, maximumContentCharacters);
     if (content === undefined)
         return undefined;
-    const metadata = isRecord(data.metadata) ? data.metadata : undefined;
     return {
         content: content.content,
         truncated: content.truncated,
-        ...remoteMetadata(metadata, maximumUrlCharacters),
+        ...metadata,
     };
 }
 function isRecord(value) {

package/lib/providers/smart-direct-child.js

@@ -109,6 +109,7 @@ async function smartDirectChildMain() {
                 'content-length',
                 'content-disposition',
                 'content-encoding',
+                'cf-mitigated',
                 'location',
                 'retry-after',
             ]);
@@ -128,8 +129,9 @@ async function smartDirectChildMain() {
                 finish({ error: 'invalid_response' }, 1);
                 return;
             }
+            const challengeMitigated = selected['cf-mitigated']?.trim().toLowerCase() === 'challenge';
             const contentLengthHeader = selected['content-length'];
-            if (contentLengthHeader !== undefined) {
+            if (!challengeMitigated && contentLengthHeader !== undefined) {
                 if (!/^\d+$/.test(contentLengthHeader)) {
                     await response.body?.cancel();
                     finish({ error: 'invalid_response' }, 1);
@@ -165,7 +167,8 @@ async function smartDirectChildMain() {
                 'text/x-markdown',
                 'application/markdown',
             ].includes(mime ?? '');
-            const shouldRead = status >= 200
+            const shouldRead = !challengeMitigated
+                && status >= 200
                 && status <= 299
                 && disposition !== 'attachment'
                 && mimeSupported

package/lib/providers/smart-direct-transport.js

@@ -2,6 +2,7 @@ import { PassThrough, Transform, Writable, } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
 import { createBrotliDecompress, createGunzip, createInflate, } from 'node:zlib';
 import { isProviderError, parseRetryAfterMs, ProviderError, providerHttpError, RETRYABLE_HTTP_STATUSES, throwIfAborted, } from '../provider-runtime/index.js';
+import { isLikelyAntiBotChallenge } from './web-extract-common.js';
 const PROVIDER = 'smart_direct';
 const CAPABILITY = 'web_extract';
 const HTTP_REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
@@ -223,6 +224,10 @@ export async function settleSmartDirectWreqResponse(response, input, dependencie
     if (!Number.isInteger(statusCode) || statusCode < 100 || statusCode > 599) {
         throw new ProviderError({ capability: CAPABILITY, kind: 'invalid_response', provider: PROVIDER });
     }
+    if (isLikelyAntiBotChallenge('', statusCode, scalarHeader(response, 'cf-mitigated'))) {
+        await discardBody(response, input.signal);
+        return { kind: 'unavailable', statusCode, url: response.url };
+    }
     const contentType = scalarHeader(response, 'content-type');
     const contentLength = parseContentLength(scalarHeader(response, 'content-length'));
     const contentDisposition = scalarHeader(response, 'content-disposition');

package/lib/providers/smart-direct.d.ts

@@ -39,7 +39,8 @@ export declare function smartDirectMarkdownToText(markdown: string): string;
 /**
  * Production smart_direct route: wreq browser TLS/HTTP fingerprint transport,
  * bounded linkedom DOM construction, and Defuddle readable-content cleaning.
- * It is not browser automation and executes no page JavaScript.
+ * Recognizable anti-bot interstitials are unavailable rather than extracted as
+ * evidence. This is not browser automation and executes no page JavaScript.
  */
 export declare class SmartDirectProvider implements WebExtractAdapter {
     readonly route: "smart_direct";