Add web capability seam: ctx.web, search/fetch providers, web tools

Introduce web access as a first-class capability seam so the model-facing web tools stay stable while backends change. dsh-web owns ctx.web as a provider registry with registration-order-independent selection and the WebError taxonomy; dsh-web-search-exa, dsh-web-search-perplexity, and dsh-web-fetch-local register capabilities into it; dsh-tool-web is the sole owner of the model-facing web_search/web_fetch schemas, prompt sections, and HTML-to-markdown presentation. Search and fetch are deliberately one seam. Providers ship as namespace plugins that register into ctx.web (like an LlmAdapter into ctx.llm), not key-owning services, since multiple search providers cannot each own the key. Tool registration follows product enablement, not backend availability, so load order/credentials never enter the model contract; the seam resolves the provider at execution time and surfaces a structured WebError otherwise. Moves the RFC to implemented/ amended to match what shipped. Example/app configs are intentionally not wired yet (RFC migration step 6).
2026-06-25 15:04:12 +08:00
parent a4091daa3d
commit d01f5f73b7
50 changed files with 3610 additions and 8 deletions
@@ -0,0 +1,87 @@
+/**
+ * The model-facing `web_fetch` tool: retrieve the content of a specific URL.
+ * Execution goes through `ctx.web` — this module owns the model-facing schema,
+ * argument validation, and PRESENTATION (HTML→markdown, truncation formatting),
+ * while the fetch provider owns safe retrieval (transport, redirects, caps).
+ *
+ * @module @deepseek-ai/dsh-tool-web/fetch
+ */
+
+import type { Context } from 'cordis'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { ToolCallPresentation } from '@deepseek-ai/dsh-tools'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import type { WebFetchBody, WebFetchResult } from '@deepseek-ai/dsh-web'
+import { assertNever } from '@deepseek-ai/dsh-llm'
+import type {} from '@deepseek-ai/dsh-system-prompt'
+import { htmlToMarkdown } from './html.ts'
+
+/** Validate value constraints the schema DSL can't express. */
+export function parseFetchArgs(args: { url: string; timeout_ms?: number }): { url: string; timeoutMs?: number } {
+  if (args.url.trim().length === 0) throw new Error('url must be a non-empty string')
+  if (args.timeout_ms !== undefined && (!Number.isFinite(args.timeout_ms) || args.timeout_ms <= 0)) {
+    throw new Error('timeout_ms must be a positive number')
+  }
+  return { url: args.url, ...args.timeout_ms !== undefined ? { timeoutMs: args.timeout_ms } : {} }
+}
+
+/** Render a fetched body to model-facing markdown text. */
+export function renderBody(body: WebFetchBody): string {
+  switch (body.kind) {
+    case 'html':
+      return htmlToMarkdown(body.content)
+    case 'text':
+      return body.content
+    /* v8 ignore next 2 -- WebFetchBody is a closed union; this arm is unreachable and only makes adding a kind a compile error. */
+    default:
+      return assertNever(body, 'unhandled web fetch body kind')
+  }
+}
+
+/** Format a fetch result as one model-facing text block. */
+export function formatFetchOutput(result: WebFetchResult): string {
+  const header = `Fetched ${result.url} (HTTP ${result.statusCode})`
+  const footer = result.truncated ? '\n\n(Content truncated. Fetch a more specific URL or section for the full text.)' : ''
+  return `${header}\n\n${renderBody(result.body)}${footer}`
+}
+
+/** Pending-call presentation: a fetch card titled by the URL. */
+export function presentFetchCall(args: { url: string; timeout_ms?: number }): ToolCallPresentation {
+  return { title: args.url, kind: 'fetch', rawInput: args.url }
+}
+
+/** Register the `web_fetch` tool and its system-prompt guidance. */
+export function apply(ctx: Context): void {
+  ctx.systemPrompt.section({
+    name: 'tool:web_fetch',
+    order: 111,
+    text: 'Use the web_fetch tool to retrieve the content of a specific HTTP(S) URL (for example a result from web_search). It returns the page content decoded to text. Cite the URL as a markdown link when you use its content.',
+  })
+
+  ctx.tools.register(defineTool({
+    name: 'web_fetch',
+    description: 'Fetch the content of a specific HTTP(S) URL and return it decoded to text.',
+    parameters: {
+      url: { type: 'string', required: true, description: 'The HTTP(S) URL to fetch.' },
+      timeout_ms: { type: 'number', description: 'Optional fetch timeout in milliseconds (capped by the provider).' },
+    },
+    async execute(args, exec): Promise<ContentBlock[]> {
+      const input = parseFetchArgs(args)
+      const result = await ctx.web.fetch(
+        { url: input.url, ...input.timeoutMs !== undefined ? { timeoutMs: input.timeoutMs } : {} },
+        exec.signal ? { signal: exec.signal } : undefined,
+      )
+      return [{ type: 'text', text: formatFetchOutput(result) }]
+    },
+    presentCall: presentFetchCall,
+  }))
+}
+
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'web-fetch'
+
+/** Services required by the `web_fetch` tool plugin. */
+export const inject = ['tools', 'web', 'systemPrompt']
+
+/** Named helper for direct registration in the root plugin and tests. */
+export const applyWebFetchTool = apply