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
--- a/packages/web/tool-web/README.md
+++ b/packages/web/tool-web/README.md
@@ -0,0 +1,30 @@
+# @deepseek-ai/dsh-tool-web
+
+The model-facing web tool suite — `web_search` and `web_fetch` — over the [web capability seam](../web/README.md) (`ctx.web`). It owns model-facing concerns only: tool names, JSON schemas, snake_case argument names, prompt sections, the result-count bound, result formatting, HTML→markdown presentation, and `presentCall`. All web access goes through `ctx.web`; this package never imports a concrete provider.
+
+Each tool is also a subpath plugin (`@deepseek-ai/dsh-tool-web/search`, `/fetch`) for focused deployments.
+
+## Tools
+
+| Tool | Args | Behavior |
+|---|---|---|
+| `web_search` | `query` (string) | Discovery. Returns an optional answer plus source URLs. `max_results` is **not** model-facing — the tool sets the bound (`WEB_SEARCH_MAX_RESULTS = 8`) and passes it to the seam. |
+| `web_fetch` | `url` (string), `timeout_ms` (number, optional) | Retrieves a specific URL. HTML bodies are rendered to markdown-ish text; text bodies pass through. A non-2xx status is reported, not an error. |
+
+## Config
+
+| Key | Default | Meaning |
+|---|---|---|
+| `search` | `true` | Register `web_search`. |
+| `fetch` | `true` | Register `web_fetch`. |
+
+```yaml
+- id: tool-web
+  name: '@deepseek-ai/dsh-tool-web'
+```
+
+## Stable registration
+
+Tool registration follows product **enablement**, not backend availability. A tool stays visible even when its selected provider is missing, misconfigured, ambiguous, or temporarily unavailable; the seam resolves the provider at execution time and execution fails with a structured `WebError` (e.g. `WEB_PROVIDER_UNAVAILABLE`, `WEB_PROVIDER_AMBIGUOUS`), which `ToolRegistry.execute()` turns into an error tool result the model can read and hooks/UI can route on. This keeps the model schema stable without making plugin load order, credential state, or HMR timing part of the model-facing contract. To remove a web tool entirely, disable it here in config.
+
+The tool reads only the aggregated `ctx.web.searchStatus()` / `fetchStatus()` for diagnostics — never each provider's `status()` directly — so provider selection has one owner.
--- a/packages/web/tool-web/package.json
+++ b/packages/web/tool-web/package.json
@@ -0,0 +1,42 @@
+{
+  "name": "@deepseek-ai/dsh-tool-web",
+  "description": "Model-facing web tools (web_search, web_fetch) over the DeepSeek Harness web capability seam (ctx.web)",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".":       { "types": "./lib/index.d.ts",  "default": "./lib/index.js" },
+    "./search": { "types": "./lib/search.d.ts", "default": "./lib/search.js" },
+    "./fetch":  { "types": "./lib/fetch.d.ts",  "default": "./lib/fetch.js" },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-llm": "^0.0.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.0.1",
+    "@deepseek-ai/dsh-tools": "^0.0.1",
+    "@deepseek-ai/dsh-web": "^0.0.1",
+    "cordis": "^4.0.0-rc.6"
+  },
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-system-prompt": "workspace:^",
+    "@deepseek-ai/dsh-tools": "workspace:^",
+    "@deepseek-ai/dsh-web": "workspace:^",
+    "@deepseek-ai/dsh-web-fetch-local": "workspace:^",
+    "@deepseek-ai/dsh-web-search-exa": "workspace:^",
+    "cordis": "^4.0.0-rc.6"
+  }
+}
--- a/packages/web/tool-web/src/fetch.ts
+++ b/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
--- a/packages/web/tool-web/src/html.ts
+++ b/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
+}
--- a/packages/web/tool-web/src/index.ts
+++ b/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)
+}
+
--- a/packages/web/tool-web/src/search.ts
+++ b/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
--- a/packages/web/tool-web/tests/integration.spec.ts
+++ b/packages/web/tool-web/tests/integration.spec.ts
@@ -0,0 +1,99 @@
+/**
+ * Integration: the real fetch backend (`dsh-web-fetch-local`) + a real search
+ * provider (`dsh-web-search-exa`) + the real seam (`dsh-web`) + the model tool
+ * (`dsh-tool-web`), exercised through `ctx.tools.execute()` — nothing bypasses
+ * the tool registry. Fetch hits a real loopback HTTP server (verifying the
+ * WORLD); search runs the real Exa provider over a stubbed global `fetch` (the
+ * network is the one boundary we mock).
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http'
+import { AddressInfo } from 'node:net'
+import { Context } from 'cordis'
+import { CallId } from '@deepseek-ai/dsh-llm'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry from '@deepseek-ai/dsh-tools'
+import WebService from '@deepseek-ai/dsh-web'
+import * as WebFetchLocal from '@deepseek-ai/dsh-web-fetch-local'
+import * as WebSearchExa from '@deepseek-ai/dsh-web-search-exa'
+import * as ToolWeb from '@deepseek-ai/dsh-tool-web'
+
+type Handler = (req: IncomingMessage, res: ServerResponse) => void
+
+let server: Server
+let base: string
+let handler: Handler
+let ctx: Context
+let fiber: Awaited<ReturnType<Context['plugin']>>
+
+beforeEach(async () => {
+  handler = (_req, res) => { res.writeHead(200, { 'content-type': 'text/html' }); res.end('<h1>Hello</h1><p>World</p>') }
+  server = createServer((req, res) => { handler(req, res) })
+  await new Promise<void>(resolve => server.listen(0, '127.0.0.1', resolve))
+  base = `http://127.0.0.1:${(server.address() as AddressInfo).port}`
+
+  ctx = new Context()
+  await ctx.plugin(SystemPrompt)
+  await ctx.plugin(ToolRegistry)
+  await ctx.plugin(WebService, { searchProvider: WebSearchExa.EXA_PROVIDER_ID, fetchProvider: WebFetchLocal.LOCAL_FETCH_PROVIDER_ID })
+  await ctx.plugin(WebFetchLocal, {})
+  await ctx.plugin(WebSearchExa, { apiKey: 'exa-key', baseURL: 'https://api.exa.test' })
+  fiber = await ctx.plugin(ToolWeb)
+})
+
+afterEach(async () => {
+  await fiber.dispose()
+  vi.unstubAllGlobals()
+  await new Promise<void>(resolve => server.close(() => { resolve() }))
+})
+
+let counter = 0
+type ToolResult = { isError: boolean; content: { type: string; text?: string }[]; error?: { code: string } }
+function call(name: string, args: unknown): Promise<ToolResult> {
+  return ctx.tools.execute({ callId: CallId(`call-${++counter}`), name, arguments: args })
+}
+
+describe('web_fetch integration over the real backend', () => {
+  it('fetches an html page and renders it to markdown', async () => {
+    const out = await call('web_fetch', { url: base })
+    expect(out.isError).toBe(false)
+    const text = out.content.map(b => b.text).join('')
+    expect(text).toContain(`Fetched ${base}`)
+    expect(text).toContain('# Hello')
+    expect(text).toContain('World')
+  })
+
+  it('reports a 404 as a result, not an error', async () => {
+    handler = (_req, res) => { res.writeHead(404, { 'content-type': 'text/plain' }); res.end('missing') }
+    const out = await call('web_fetch', { url: base })
+    expect(out.isError).toBe(false)
+    expect(out.content.map(b => b.text).join('')).toContain('HTTP 404')
+  })
+
+  it('surfaces WEB_INVALID_URL as a structured tool error', async () => {
+    const out = await call('web_fetch', { url: 'ftp://example.com' })
+    expect(out.isError).toBe(true)
+    expect(out.error?.code).toBe('WEB_INVALID_URL')
+  })
+
+  it('surfaces a blocked cross-origin redirect as WEB_REDIRECT_BLOCKED', async () => {
+    handler = (_req, res) => { res.writeHead(302, { location: 'https://example.com/' }); res.end() }
+    const out = await call('web_fetch', { url: base })
+    expect(out.isError).toBe(true)
+    expect(out.error?.code).toBe('WEB_REDIRECT_BLOCKED')
+  })
+})
+
+describe('web_search integration over the real Exa provider', () => {
+  it('runs web_search end-to-end and formats the provider result', async () => {
+    vi.stubGlobal('fetch', vi.fn(async () => new Response(
+      JSON.stringify({ results: [{ url: 'https://result.test', title: 'Result', highlights: ['a highlight'] }] }),
+      { status: 200, headers: { 'content-type': 'application/json' } },
+    )))
+    const out = await call('web_search', { query: 'deepseek' })
+    expect(out.isError).toBe(false)
+    expect(out.content.map(b => b.text).join('')).toContain('[Result](https://result.test)')
+  })
+})
+
--- a/packages/web/tool-web/tests/load-path.spec.ts
+++ b/packages/web/tool-web/tests/load-path.spec.ts
@@ -0,0 +1,49 @@
+/**
+ * Real-load-path guard for @deepseek-ai/dsh-tool-web. `tool-web` is a NAMESPACE
+ * plugin with `inject` — so a stray `export default apply` would make the cordis
+ * Loader's `unwrapExports` (`exports.default ?? exports`) collapse the module to
+ * the bare `apply` function, DROPPING `inject`. The plugin would then read
+ * `ctx.web` without having injected it and throw `cannot get property … without
+ * inject` the moment it loads (postmortem 0001).
+ *
+ * A hand-built `ctx.plugin({ apply, inject })` mount CANNOT catch that — it
+ * bypasses `unwrapExports`. So this test unwraps the module through the REAL
+ * `Loader.prototype.unwrapExports` and mounts the result over `ctx.web`,
+ * exercising the exact path the Loader uses. Prove the guard bites: add
+ * `export default apply` to `src/index.ts`, watch this go red, revert.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import Loader from '@cordisjs/plugin-loader'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry from '@deepseek-ai/dsh-tools'
+import WebService from '@deepseek-ai/dsh-web'
+import * as toolWeb from '@deepseek-ai/dsh-tool-web'
+
+describe('dsh-tool-web real-load-path guard', () => {
+  it('has no default export and keeps name/inject/Config through unwrapExports', () => {
+    expect('default' in toolWeb).toBe(false)
+
+    const loader = Object.create(Loader.prototype) as Loader
+    const unwrapped = loader.unwrapExports(toolWeb) as Record<string, unknown>
+    expect(unwrapped).toBe(toolWeb)
+    expect(unwrapped.name).toBe('tool-web')
+    expect(unwrapped.inject).toEqual(['tools', 'web', 'systemPrompt'])
+    expect(typeof unwrapped.apply).toBe('function')
+  })
+
+  it('boots over ctx.web through the unwrapped module without an inject error', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry)
+    await ctx.plugin(WebService, {})
+
+    const loader = Object.create(Loader.prototype) as Loader
+    const unwrapped = loader.unwrapExports(toolWeb) as Parameters<Context['plugin']>[0]
+    // A collapsed export shape (dropped inject) would throw "without inject" here.
+    const fiber = await ctx.plugin(unwrapped)
+    expect(ctx.tools.schemas().map(s => s.name)).toEqual(expect.arrayContaining(['web_search', 'web_fetch']))
+    await fiber.dispose()
+  })
+})
--- a/packages/web/tool-web/tests/tool-web.spec.ts
+++ b/packages/web/tool-web/tests/tool-web.spec.ts
@@ -0,0 +1,281 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { CallId } from '@deepseek-ai/dsh-llm'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry from '@deepseek-ai/dsh-tools'
+import WebService from '@deepseek-ai/dsh-web'
+import type { WebSearchProvider, WebSearchResult, WebProviderStatus } from '@deepseek-ai/dsh-web'
+import * as ToolWeb from '@deepseek-ai/dsh-tool-web'
+import {
+  formatSearchOutput,
+  formatFetchOutput,
+  parseSearchArgs,
+  parseFetchArgs,
+  presentSearchCall,
+  presentFetchCall,
+  renderBody,
+  htmlToMarkdown,
+} from '@deepseek-ai/dsh-tool-web'
+
+const available: WebProviderStatus = { available: true }
+
+function searchProvider(result: WebSearchResult, status: WebProviderStatus = available): WebSearchProvider {
+  return { id: 'stub-search', status: () => status, search: () => Promise.resolve(result) }
+}
+
+/** Mount the real registry, seam, and tool-web; return an executor helper. */
+async function mountTools(opts: {
+  config?: ToolWeb.Config
+  webConfig?: ConstructorParameters<typeof WebService>[1]
+  search?: WebSearchProvider
+  fetchProvider?: import('@deepseek-ai/dsh-web').WebFetchProvider
+} = {}): Promise<{ ctx: Context; fiber: Awaited<ReturnType<Context['plugin']>>; call: (name: string, args: unknown) => Promise<{ isError: boolean; content: { type: string; text?: string }[]; error?: { code: string } }> }> {
+  const ctx = new Context()
+  await ctx.plugin(SystemPrompt)
+  await ctx.plugin(ToolRegistry)
+  await ctx.plugin(WebService, opts.webConfig ?? {})
+  if (opts.search) ctx.web.registerSearchProvider(opts.search)
+  if (opts.fetchProvider) ctx.web.registerFetchProvider(opts.fetchProvider)
+  const fiber = await ctx.plugin(ToolWeb, opts.config ?? {})
+  let counter = 0
+  const call = (name: string, args: unknown) => ctx.tools.execute({ callId: CallId(`call-${++counter}`), name, arguments: args }) as never
+  return { ctx, fiber, call }
+}
+
+describe('search formatting', () => {
+  it('renders content, sources with titles/hostnames, snippets, and a citation reminder', () => {
+    const out = formatSearchOutput({
+      providerId: 'p', query: 'q', content: 'an answer', truncated: false,
+      sources: [
+        { url: 'https://a.test/x', title: 'A', snippet: 'about a', publishedAt: '2026-01-01' },
+        { url: 'https://b.test/y' },
+      ],
+    })
+    expect(out).toContain('an answer')
+    expect(out).toContain('[A](https://a.test/x) — about a (2026-01-01)')
+    expect(out).toContain('[b.test](https://b.test/y)')
+    expect(out).toContain('Cite the relevant URLs')
+  })
+
+  it('reports no results when there is neither content nor sources', () => {
+    expect(formatSearchOutput({ providerId: 'p', query: 'q', sources: [], truncated: false }))
+      .toContain('No results found.')
+  })
+
+  it('renders content alone when there are no sources', () => {
+    const out = formatSearchOutput({ providerId: 'p', query: 'q', content: 'just an answer', sources: [], truncated: false })
+    expect(out).toContain('just an answer')
+    expect(out).not.toContain('No results found.')
+    expect(out).not.toContain('Sources:')
+  })
+
+  it('notes truncation', () => {
+    const out = formatSearchOutput({ providerId: 'p', query: 'q', sources: [{ url: 'https://a.test' }], truncated: true })
+    expect(out).toContain('Showing the first 1 sources')
+  })
+
+  it('validates the query', () => {
+    expect(() => parseSearchArgs({ query: '   ' })).toThrow('non-empty')
+    expect(parseSearchArgs({ query: 'hi' })).toEqual({ query: 'hi' })
+  })
+
+  it('presents a search call as a search-kind card titled by the query', () => {
+    expect(presentSearchCall({ query: 'find me' })).toEqual({ title: 'find me', kind: 'search', rawInput: 'find me' })
+  })
+})
+
+describe('fetch formatting', () => {
+  it('renders an html body to markdown text with a status header', () => {
+    const out = formatFetchOutput({
+      providerId: 'p', url: 'https://a.test', statusCode: 200, truncated: false,
+      body: { kind: 'html', content: '<h1>Title</h1><p>Body text</p>' },
+    })
+    expect(out).toContain('Fetched https://a.test (HTTP 200)')
+    expect(out).toContain('# Title')
+    expect(out).toContain('Body text')
+  })
+
+  it('passes a text body through and notes truncation', () => {
+    const out = formatFetchOutput({
+      providerId: 'p', url: 'https://a.test', statusCode: 200, truncated: true,
+      body: { kind: 'text', content: 'plain' },
+    })
+    expect(out).toContain('plain')
+    expect(out).toContain('Content truncated')
+  })
+
+  it('renderBody dispatches on kind', () => {
+    expect(renderBody({ kind: 'text', content: 'x' })).toBe('x')
+    expect(renderBody({ kind: 'html', content: '<p>y</p>' })).toBe('y')
+  })
+
+  it('validates url and timeout', () => {
+    expect(() => parseFetchArgs({ url: ' ' })).toThrow('non-empty')
+    expect(() => parseFetchArgs({ url: 'https://a.test', timeout_ms: -1 })).toThrow('positive')
+    expect(parseFetchArgs({ url: 'https://a.test', timeout_ms: 5 })).toEqual({ url: 'https://a.test', timeoutMs: 5 })
+  })
+
+  it('presents a fetch call as a fetch-kind card titled by the url', () => {
+    expect(presentFetchCall({ url: 'https://a.test' })).toEqual({ title: 'https://a.test', kind: 'fetch', rawInput: 'https://a.test' })
+  })
+})
+
+describe('htmlToMarkdown', () => {
+  it('drops scripts/styles, keeps text, decodes entities, converts links', () => {
+    const md = htmlToMarkdown('<style>.x{}</style><script>bad()</script><p>Tom &amp; Jerry</p><a href="https://a.test">link</a>')
+    expect(md).not.toContain('bad()')
+    expect(md).not.toContain('.x{}')
+    expect(md).toContain('Tom & Jerry')
+    expect(md).toContain('[link](https://a.test)')
+  })
+
+  it('decodes numeric entities and collapses whitespace', () => {
+    expect(htmlToMarkdown('<p>a&#39;b</p>')).toBe("a'b")
+    expect(htmlToMarkdown('<div>x</div>\n\n\n<div>y</div>')).toBe('x\n\ny')
+  })
+
+  it('decodes hex entities and named entities, and leaves unknown/out-of-range ones intact', () => {
+    expect(htmlToMarkdown('<p>&#x41;&#X42;</p>')).toBe('AB')
+    expect(htmlToMarkdown('<p>&copy; &mdash;</p>')).toBe('© —')
+    expect(htmlToMarkdown('<p>&notareal;</p>')).toBe('&notareal;')
+    // An out-of-range code point keeps the original entity text (fromCodePoint fallback).
+    expect(htmlToMarkdown('<p>&#x110000;</p>')).toBe('&#x110000;')
+    expect(htmlToMarkdown('<p>&#1114112;</p>')).toBe('&#1114112;')
+  })
+
+  it('renders a link with an empty label as its bare href', () => {
+    expect(htmlToMarkdown('<a href="https://a.test"></a>')).toBe('https://a.test')
+  })
+
+  it('converts headings and list items to markdown', () => {
+    expect(htmlToMarkdown('<h2>Heading</h2><p>after</p>')).toContain('## Heading')
+    const list = htmlToMarkdown('<ul><li>one</li><li>two</li></ul>')
+    expect(list).toContain('- one')
+    expect(list).toContain('- two')
+  })
+
+  it('falls back to the raw URL as a source label when the URL is unparseable', () => {
+    const out = formatSearchOutput({ providerId: 'p', query: 'q', truncated: false, sources: [{ url: 'not a url' }] })
+    expect(out).toContain('[not a url](not a url)')
+  })
+})
+
+describe('tool-web registration', () => {
+  it('registers both tools by default', async () => {
+    const { fiber, ctx } = await mountTools()
+    const names = ctx.tools.schemas().map(s => s.name)
+    expect(names).toContain('web_search')
+    expect(names).toContain('web_fetch')
+    await fiber.dispose()
+    expect(ctx.tools.schemas().map(s => s.name)).not.toContain('web_search')
+  })
+
+  it('registers only enabled tools', async () => {
+    const { fiber, ctx } = await mountTools({ config: { search: true, fetch: false } })
+    const names = ctx.tools.schemas().map(s => s.name)
+    expect(names).toContain('web_search')
+    expect(names).not.toContain('web_fetch')
+    await fiber.dispose()
+  })
+
+  it('registers only web_fetch when search is disabled', async () => {
+    const { fiber, ctx } = await mountTools({ config: { search: false, fetch: true } })
+    const names = ctx.tools.schemas().map(s => s.name)
+    expect(names).not.toContain('web_search')
+    expect(names).toContain('web_fetch')
+    await fiber.dispose()
+  })
+
+  it('registers web_search even when no provider is available (schema follows enablement, not availability)', async () => {
+    const { fiber, ctx } = await mountTools()
+    expect(ctx.tools.schemas().map(s => s.name)).toContain('web_search')
+    expect(ctx.web.searchStatus()).toEqual({ available: false, reason: 'none' })
+    await fiber.dispose()
+  })
+
+  it('contributes prompt sections for the enabled tools', async () => {
+    const { fiber, ctx } = await mountTools()
+    const prompt = await ctx.systemPrompt.assemble()
+    const text = prompt.sections.map(s => (typeof s.text === 'function' ? s.text() : s.text)).join('\n')
+    expect(text).toContain('web_search')
+    expect(text).toContain('web_fetch')
+    await fiber.dispose()
+  })
+})
+
+describe('tool-web execution through the real registry', () => {
+  it('executes web_search and formats the result', async () => {
+    const result: WebSearchResult = {
+      providerId: 'stub-search', query: 'q', content: 'answer', truncated: false,
+      sources: [{ url: 'https://a.test', title: 'A', snippet: 'snip' }],
+    }
+    const { fiber, call } = await mountTools({ webConfig: { searchProvider: 'stub-search' }, search: searchProvider(result) })
+    const out = await call('web_search', { query: 'q' })
+    expect(out.isError).toBe(false)
+    expect(out.content.map(b => b.text).join('')).toContain('[A](https://a.test)')
+    await fiber.dispose()
+  })
+
+  it('surfaces a structured WebError when no provider is available', async () => {
+    const { fiber, call } = await mountTools()
+    const out = await call('web_search', { query: 'q' })
+    expect(out.isError).toBe(true)
+    expect(out.error?.code).toBe('WEB_PROVIDER_UNAVAILABLE')
+    await fiber.dispose()
+  })
+
+  it('surfaces WEB_PROVIDER_AMBIGUOUS for multiple unconfigured providers', async () => {
+    const { ctx, fiber, call } = await mountTools({ search: searchProvider({ providerId: 'stub-search', query: 'q', sources: [], truncated: false }) })
+    ctx.web.registerSearchProvider({ id: 'other', status: () => available, search: () => Promise.resolve({ providerId: 'other', query: 'q', sources: [], truncated: false }) })
+    const out = await call('web_search', { query: 'q' })
+    expect(out.isError).toBe(true)
+    expect(out.error?.code).toBe('WEB_PROVIDER_AMBIGUOUS')
+    await fiber.dispose()
+  })
+
+  it('rejects invalid arguments with a structured INVALID_ARGS error', async () => {
+    const { fiber, call } = await mountTools({ webConfig: { searchProvider: 'stub-search' }, search: searchProvider({ providerId: 'stub-search', query: 'q', sources: [], truncated: false }) })
+    const out = await call('web_search', { query: 123 })
+    expect(out.isError).toBe(true)
+    expect(out.error?.code).toBe('INVALID_ARGS')
+    await fiber.dispose()
+  })
+
+  it('has no default export (namespace plugin export shape)', () => {
+    expect('default' in ToolWeb).toBe(false)
+  })
+
+  it('executes web_fetch, forwarding timeout_ms and the abort signal to the seam', async () => {
+    const seen: { request?: { url: string; timeoutMs?: number }; signal?: AbortSignal | undefined } = {}
+    const fetchProvider = {
+      id: 'stub-fetch',
+      status: () => available,
+      fetch: (request: { url: string; timeoutMs?: number }, exec?: { signal?: AbortSignal }) => {
+        seen.request = request
+        seen.signal = exec?.signal
+        return Promise.resolve({ providerId: 'stub-fetch', url: request.url, statusCode: 200, body: { kind: 'text' as const, content: 'ok' }, truncated: false })
+      },
+    }
+    const { ctx, fiber } = await mountTools({ webConfig: { fetchProvider: 'stub-fetch' }, fetchProvider })
+    const controller = new AbortController()
+    const out = await ctx.tools.execute({ callId: CallId('fetch-1'), name: 'web_fetch', arguments: { url: 'https://a.test', timeout_ms: 1234 }, signal: controller.signal })
+    expect(out.isError).toBe(false)
+    expect(seen.request).toEqual({ url: 'https://a.test', timeoutMs: 1234 })
+    expect(seen.signal).toBe(controller.signal)
+    await fiber.dispose()
+  })
+
+  it('executes web_search, forwarding the abort signal to the seam', async () => {
+    const seen: { signal?: AbortSignal | undefined } = {}
+    const provider: WebSearchProvider = {
+      id: 'stub-search',
+      status: () => available,
+      search: (_request, exec) => { seen.signal = exec?.signal; return Promise.resolve({ providerId: 'stub-search', query: 'q', sources: [], truncated: false }) },
+    }
+    const { ctx, fiber } = await mountTools({ webConfig: { searchProvider: 'stub-search' }, search: provider })
+    const controller = new AbortController()
+    await ctx.tools.execute({ callId: CallId('search-1'), name: 'web_search', arguments: { query: 'q' }, signal: controller.signal })
+    expect(seen.signal).toBe(controller.signal)
+    await fiber.dispose()
+  })
+})
--- a/packages/web/tool-web/tsconfig.json
+++ b/packages/web/tool-web/tsconfig.json
@@ -0,0 +1,17 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib"
+  },
+  "include": ["src"],
+  "references": [
+    { "path": "../../../vendor/cosmokit" },
+    { "path": "../../../vendor/cordis" },
+    { "path": "../../../vendor/schemastery" },
+    { "path": "../../llm/llm" },
+    { "path": "../../core/tools" },
+    { "path": "../../core/system-prompt" },
+    { "path": "../web" }
+  ]
+}
--- a/packages/web/tool-web/tsdown.config.ts
+++ b/packages/web/tool-web/tsdown.config.ts
@@ -0,0 +1,18 @@
+import { defineConfig } from 'tsdown'
+
+/**
+ * tool-web exposes one package root plus one entry per tool plugin, so each tool
+ * can be loaded or replaced independently as a subpath plugin
+ * (`@deepseek-ai/dsh-tool-web/search`, `/fetch`). The root tsdown config only
+ * auto-discovers `src/index.ts`, so the subpath entries are declared here.
+ */
+export default defineConfig({
+  entry: ['src/index.ts', 'src/search.ts', 'src/fetch.ts'],
+  outDir: 'lib',
+  format: ['esm'],
+  platform: 'node',
+  target: 'es2024',
+  fixedExtension: false,
+  dts: false,
+  clean: false,
+})