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).

packages/web/tool-web/src/fetch.ts

@@ -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

packages/web/tool-web/src/html.ts

@@ -0,0 +1,85 @@
+/**
+ * Minimal, dependency-free HTML→markdown-ish text conversion for `web_fetch`
+ * presentation. This is intentionally NOT a full HTML parser: it strips
+ * script/style/noscript, drops tags, decodes the common named/numeric entities,
+ * and collapses whitespace into a readable plain-text approximation with a few
+ * markdown affordances (headings, list bullets, links). A heavier converter can
+ * replace this without touching the seam or the tool schema.
+ *
+ * @module @deepseek-ai/dsh-tool-web/html
+ */
+
+/** Decode the handful of HTML entities common in textual content. */
+function decodeEntities(text: string): string {
+  return text
+    .replace(/&(#[xX][0-9a-fA-F]+|#[0-9]+|[a-zA-Z]+);/g, (match, entity: string) => {
+      if (entity.startsWith('#x') || entity.startsWith('#X')) {
+        const code = Number.parseInt(entity.slice(2), 16)
+        return safeFromCodePoint(code, match)
+      }
+      if (entity.startsWith('#')) {
+        const code = Number.parseInt(entity.slice(1), 10)
+        return safeFromCodePoint(code, match)
+      }
+      return NAMED_ENTITIES[entity] ?? match
+    })
+}
+
+const NAMED_ENTITIES: Record<string, string> = {
+  amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ',
+  copy: '©', reg: '®', trade: '™', hellip: '…', mdash: '—', ndash: '–',
+}
+
+function safeFromCodePoint(code: number, fallback: string): string {
+  try {
+    return String.fromCodePoint(code)
+  } catch {
+    // An out-of-range code point (RangeError) is the only failure here; keep the
+    // original entity text rather than throwing out of pure presentation.
+    return fallback
+  }
+}
+
+/**
+ * Convert an HTML document to a readable markdown-ish text approximation.
+ * Best-effort and lossy by design — fidelity is the job of a future heavier
+ * converter, not this fallback.
+ */
+export function htmlToMarkdown(html: string): string {
+  let text = html
+    // Drop non-content elements entirely (including their contents).
+    .replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, '')
+    .replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, '')
+    .replace(/<noscript\b[^>]*>[\s\S]*?<\/noscript>/gi, '')
+    .replace(/<!--[\s\S]*?-->/g, '')
+
+  // Convert links to markdown before stripping tags.
+  text = text.replace(/<a\b[^>]*\bhref\s*=\s*["']([^"']*)["'][^>]*>([\s\S]*?)<\/a>/gi, (_match, href: string, label: string) => {
+    const cleanLabel = label.replace(/<[^>]+>/g, '').trim()
+    return cleanLabel.length > 0 ? `[${cleanLabel}](${href})` : href
+  })
+
+  // Headings → markdown hashes.
+  text = text.replace(/<h([1-6])\b[^>]*>([\s\S]*?)<\/h\1>/gi, (_match, level: string, body: string) => {
+    const hashes = '#'.repeat(Number(level))
+    return `\n\n${hashes} ${body.replace(/<[^>]+>/g, '').trim()}\n\n`
+  })
+
+  // List items → bullets.
+  text = text.replace(/<li\b[^>]*>([\s\S]*?)<\/li>/gi, (_match, body: string) => `\n- ${body.replace(/<[^>]+>/g, '').trim()}`)
+
+  // Block-level breaks become paragraph breaks.
+  text = text
+    .replace(/<\/(p|div|section|article|header|footer|tr|table|ul|ol|blockquote)>/gi, '\n\n')
+    .replace(/<br\s*\/?>/gi, '\n')
+
+  // Drop all remaining tags, decode entities, collapse whitespace.
+  text = text.replace(/<[^>]+>/g, '')
+  text = decodeEntities(text)
+  text = text
+    .replace(/[ \t\f\v]+/g, ' ')
+    .replace(/ *\n */g, '\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim()
+  return text
+}

packages/web/tool-web/src/index.ts

@@ -0,0 +1,59 @@
+/**
+ * The model-facing web tool suite (`web_search`, `web_fetch`) over the `ctx.web`
+ * seam. This root plugin registers the tools the product has ENABLED, composing
+ * the per-tool registration helpers; each tool is also exposed as a subpath
+ * plugin (`@deepseek-ai/dsh-tool-web/search`, `/fetch`) for focused deployments.
+ *
+ * The package owns model-facing concerns only — tool names, JSON schemas,
+ * argument validation, prompt sections, result-cap constants, result formatting,
+ * HTML→markdown presentation. All web access goes through `ctx.web`; this
+ * package never imports a concrete provider package.
+ *
+ * Tool registration follows product/app ENABLEMENT, not backend availability: a
+ * tool stays visible even when its selected provider is missing/misconfigured,
+ * and execution fails with a structured `WebError` (resolved by the seam at call
+ * time). That keeps the model schema stable without making plugin load order,
+ * credential state, or HMR timing part of the model-facing contract.
+ *
+ * @module @deepseek-ai/dsh-tool-web
+ */
+
+import type { Context } from 'cordis'
+import z from 'schemastery'
+import type {} from '@deepseek-ai/dsh-web'
+import { applyWebSearchTool } from './search.ts'
+import { applyWebFetchTool } from './fetch.ts'
+
+export { WEB_SEARCH_MAX_RESULTS, applyWebSearchTool, formatSearchOutput, parseSearchArgs, presentSearchCall } from './search.ts'
+export { applyWebFetchTool, formatFetchOutput, parseFetchArgs, presentFetchCall, renderBody } from './fetch.ts'
+export { htmlToMarkdown } from './html.ts'
+
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'tool-web'
+
+/** Services required by the web tool suite. */
+export const inject = ['tools', 'web', 'systemPrompt']
+
+export interface Config {
+  /** Register `web_search`. Defaults to true. */
+  search?: boolean
+  /** Register `web_fetch`. Defaults to true. */
+  fetch?: boolean
+}
+
+export const Config: z<Config> = z.object({
+  search: z.boolean().default(true),
+  fetch: z.boolean().default(true),
+})
+
+/**
+ * Register the enabled web tools. `search`/`fetch` default to true; a product
+ * that wants only one disables the other in config. The tools' disposers are
+ * fiber-scoped (the effect-based registries clean up on dispose), so no manual
+ * teardown is needed.
+ */
+export function apply(ctx: Context, config: Config): void {
+  if (config.search !== false) applyWebSearchTool(ctx)
+  if (config.fetch !== false) applyWebFetchTool(ctx)
+}
+

packages/web/tool-web/src/search.ts

@@ -0,0 +1,105 @@
+/**
+ * The model-facing `web_search` tool: discover current information on the web.
+ * Execution goes through `ctx.web` — this module owns only the model-facing
+ * schema, argument validation, the result-count bound, and result formatting,
+ * never provider selection or network access.
+ *
+ * @module @deepseek-ai/dsh-tool-web/search
+ */
+
+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 { WebSearchResult } from '@deepseek-ai/dsh-web'
+import type {} from '@deepseek-ai/dsh-system-prompt'
+
+/**
+ * Default upper bound on returned sources. Owned by the consumer (not the
+ * provider or model), mirroring `dsh-tool-fs`'s `READ_LIMIT`/`GREP_LIMIT`. The
+ * model just asks a question; the product controls how much context returns.
+ * The default `8` aligns with OpenCode's Exa default.
+ */
+export const WEB_SEARCH_MAX_RESULTS = 8
+
+/** Validate value constraints the schema DSL can't express. */
+export function parseSearchArgs(args: { query: string }): { query: string } {
+  if (args.query.trim().length === 0) throw new Error('query must be a non-empty string')
+  return { query: args.query }
+}
+
+/** Display label for a source: its title, else its hostname. */
+function sourceLabel(url: string, title: string | undefined): string {
+  if (title !== undefined && title.length > 0) return title
+  try {
+    return new URL(url).hostname
+  } catch {
+    // A provider should return a valid URL, but never let a malformed one throw
+    // out of pure formatting — fall back to the raw string.
+    return url
+  }
+}
+
+/** Format a search result as one model-facing text block. */
+export function formatSearchOutput(result: WebSearchResult): string {
+  const parts: string[] = []
+  if (result.content !== undefined && result.content.length > 0) parts.push(result.content)
+
+  if (result.sources.length > 0) {
+    const lines = result.sources.map((source) => {
+      const label = sourceLabel(source.url, source.title)
+      const meta: string[] = []
+      if (source.snippet !== undefined && source.snippet.length > 0) meta.push(source.snippet)
+      if (source.publishedAt !== undefined && source.publishedAt.length > 0) meta.push(`(${source.publishedAt})`)
+      const suffix = meta.length > 0 ? ` — ${meta.join(' ')}` : ''
+      return `- [${label}](${source.url})${suffix}`
+    })
+    parts.push(`Sources:\n${lines.join('\n')}`)
+  } else if (result.content === undefined || result.content.length === 0) {
+    parts.push('No results found.')
+  }
+
+  if (result.truncated) parts.push(`(Showing the first ${result.sources.length} sources. Refine the query for more.)`)
+  parts.push('Cite the relevant URLs above as markdown links in your answer.')
+  return parts.join('\n\n')
+}
+
+/** Pending-call presentation: a search card titled by the query. */
+export function presentSearchCall(args: { query: string }): ToolCallPresentation {
+  return { title: args.query, kind: 'search', rawInput: args.query }
+}
+
+/** Register the `web_search` tool and its system-prompt guidance. */
+export function apply(ctx: Context): void {
+  ctx.systemPrompt.section({
+    name: 'tool:web_search',
+    order: 110,
+    text: 'Use the web_search tool to discover current information on the web. It returns an optional answer plus a list of source URLs. Follow up with web_fetch when you need the full content of a specific result, and cite the relevant URLs as markdown links.',
+  })
+
+  ctx.tools.register(defineTool({
+    name: 'web_search',
+    description: 'Search the web for current information. Returns an optional summary answer and a list of source URLs.',
+    parameters: {
+      query: { type: 'string', required: true, description: 'The search query.' },
+    },
+    async execute(args, exec): Promise<ContentBlock[]> {
+      const input = parseSearchArgs(args)
+      const result = await ctx.web.search(
+        { query: input.query, maxResults: WEB_SEARCH_MAX_RESULTS },
+        exec.signal ? { signal: exec.signal } : undefined,
+      )
+      return [{ type: 'text', text: formatSearchOutput(result) }]
+    },
+    presentCall: presentSearchCall,
+  }))
+}
+
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'web-search'
+
+/** Services required by the `web_search` tool plugin. */
+export const inject = ['tools', 'web', 'systemPrompt']
+
+/** Named helper for direct registration in the root plugin and tests. */
+export const applyWebSearchTool = apply