@deepseek-ai/dsh-web 0.0.1-rc.1

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, DeepSeek
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/web/web/README.md
+README.md: 2acb5022a83c08c33a26be626a93b7355c07a0ed
+README.zh.md: b77b0a897082dba01e10be3f7b0ca3b3f0260a9f

package/README.md

@@ -0,0 +1,61 @@
+# @deepseek-ai/dsh-web
+
+English | [中文](README.zh.md)
+
+The **`WebService`** (`ctx.web`) defines WHAT web access the harness has — search the web, fetch a URL — over multiple providers, without binding the model contract to one vendor's API shape.
+
+This package owns the Service Definition role of the web capability. Unlike bash/fs it spans two operations (search and fetch) on one seam, with potentially multiple providers each:
+
+| Package | Role |
+|---|---|
+| `@deepseek-ai/dsh-web` (this) | Service Definition: the service, provider registries, selection policy, request/result vocabulary, the `WebError` taxonomy |
+| `@deepseek-ai/dsh-web-search-exa` | Search provider: Exa |
+| `@deepseek-ai/dsh-web-search-perplexity` | Search provider: Perplexity |
+| `@deepseek-ai/dsh-web-fetch-local` | Fetch provider: anonymous public HTTP(S) |
+| `@deepseek-ai/dsh-tool-web` | Consumer: the model-facing `web_search` / `web_fetch` tool schemas over `ctx.web` |
+
+Search and fetch share no request schema and no business logic, but they are deliberately one seam: `ctx.web` is a single web-access middle layer with one provider-selection policy owner, one abort/error vocabulary, and one product-facing "how this harness reaches the web" config surface. The `Search`/`Fetch` method pairs are deliberately parallel.
+
+## Service API (`ctx.web`)
+
+| Member | Semantics |
+|---|---|
+| `registerSearchProvider(provider)` / `registerFetchProvider(provider)` | Register a backend. Throws `WebError` `WEB_DUPLICATE_PROVIDER` on a duplicate id within that capability kind. Returns a disposer. Disposed with the calling fiber. |
+| `search(request, signal?)` | Resolve the search provider and run one search. Enforces `request.maxResults` on the result (truncates `sources[]`, sets `truncated`). Throws `WebError` when the capability cannot run. |
+| `fetch(request, signal?)` | Resolve the fetch provider and retrieve one URL. A non-2xx response is a result, not a throw. Throws `WebError` for failures to safely retrieve or represent the resource. |
+
+Providers register **capabilities**, not tools. `dsh-tool-web` is the only owner of model-facing names, descriptions, prompt guidance, JSON schemas, and presentation.
+
+## Selection
+
+Selection never depends on registration, config, or HMR order. A capability has an explicit provider id (config `searchProvider`/`fetchProvider`, or env `$DSH_WEB_SEARCH_PROVIDER`/`$DSH_WEB_FETCH_PROVIDER` feeding the same fields), or auto-selects when exactly one usable provider is registered. `search()`/`fetch()` resolve the provider at execution time:
+
+| Situation | Execution |
+|---|---|
+| configured id registered and `available()` | runs that provider |
+| configured id not registered | `WEB_PROVIDER_CONFIGURED_MISSING` |
+| configured id registered but unavailable | `WEB_PROVIDER_CONFIGURED_UNAVAILABLE` |
+| no id, exactly one registered usable provider | runs it |
+| no id, no usable provider | `WEB_PROVIDER_UNAVAILABLE` |
+| no id, multiple usable providers | `WEB_PROVIDER_AMBIGUOUS` |
+
+The failure branches throw `WebError`, whose structured code (plus message detail — the missing id, the ambiguous candidate set) is the surface callers route on. A provider's own `available()` is a cheap local check (credential presence, parseable config) that feeds this execution-time selection and **must not make network calls**; `dsh-tool-web` never calls it — the tool executes through `ctx.web.search()`/`fetch()` and routes on the thrown codes, so provider selection has one owner.
+
+## Vocabulary
+
+`WebSearchRequest` (`query`, `maxResults?`) → `WebSearchResult` (`content?`, `sources[]`, `truncated`); each `WebSearchSource` has a required `url` and optional `title`/`snippet`/`publishedAt` (Perplexity citations may be URL-only). `WebFetchRequest` (`url`) → `WebFetchResult` (final `url`, `statusCode`, `body`, `truncated`); cancellation is a direct optional `AbortSignal` argument to `search()`/`fetch()`. `WebFetchBody` is a CLOSED discriminated union (`html` | `text`) owned here — consumers `switch` to exhaustiveness so a new kind breaks their compilation until handled. See `src/types.ts` for the full contracts and the `WebError` code taxonomy.
+
+## Model Experience
+
+Indirectly, through `dsh-tool-web`, which retains bounded normalized provider data or the exact configured-provider, unavailable-provider, no-provider, multiple-provider, and `Error: <message>` failures while this registry contributes no prompt or schema itself.
+
+#### KV Cache effect
+
+No direct invalidation; the named consumer owns any request-prefix changes.
+
+## Known Limitations and Deferred Work
+
+- **No observation surface** — no provider-change event and no capability-status query; availability is observed only by executing `search()`/`fetch()` and routing the thrown `WebError` codes, and the no-provider failure is the generic `WEB_PROVIDER_UNAVAILABLE` with no per-provider reason enumeration ([Agent Note](../../../.agents/notes/archived/simplification/2026-07-04-drop-unconsumed-web-observation-surface.md)).
+- **`WebSearchRequest` carries only `query` + `maxResults`** — provider-neutral controls (recency, domain filters, regional hints, search depth) are deferred until Exa and Perplexity can both honor them honestly ([seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)).
+- **`WebFetchBody` has no `pdf` arm** — text-extractable PDF support is named deferred work; the closed union makes adding it a compile-enforced change across the three web packages.
+- **Provider-backed page extraction is out of scope of `fetch()`** — a Firecrawl/Tavily-style `web_extract` capability is deferred rather than widening the fetch operation.

package/README.zh.md

@@ -0,0 +1,61 @@
+# @deepseek-ai/dsh-web
+
+[English](README.md) | 中文
+
+**`WebService`**（`ctx.web`）定义 harness 具备哪些 web 访问能力（搜索 web、抓取 URL），并通过多个提供方实现，不把模型约定绑定到某个厂商的 API 形状。
+
+本包承担 web 能力的 Service Definition 角色。与 bash/fs 不同，它在一个 seam 上跨越搜索与抓取两种操作，每种操作都可能有多个提供方：
+
+| 包 | 职责 |
+|---|---|
+| `@deepseek-ai/dsh-web`（本包） | Service Definition：服务、提供方注册表、选择策略、请求／结果词汇、`WebError` 分类体系 |
+| `@deepseek-ai/dsh-web-search-exa` | 搜索提供方：Exa |
+| `@deepseek-ai/dsh-web-search-perplexity` | 搜索提供方：Perplexity |
+| `@deepseek-ai/dsh-web-fetch-local` | 抓取提供方：匿名公共 HTTP(S) |
+| `@deepseek-ai/dsh-tool-web` | Consumer：面向模型的 `web_search`／`web_fetch` 工具 schema，构建于 `ctx.web` 之上 |
+
+搜索与抓取没有共享请求 schema 或业务逻辑，但有意共用一个 seam：`ctx.web` 是单一 web 访问中间层，拥有一项提供方选择策略、一套中止／错误词汇和一个面向产品的「该 harness 如何访问 web」配置接口。成对的 `Search`／`Fetch` 方法保持并行是有意为之。
+
+## 服务 API（`ctx.web`）
+
+| 成员 | 语义 |
+|---|---|
+| `registerSearchProvider(provider)`／`registerFetchProvider(provider)` | 注册后端。同一能力类型下 id 重复时抛出 `WebError` `WEB_DUPLICATE_PROVIDER`。返回 disposer。随调用 fiber 一并 dispose（资源释放）。 |
+| `search(request, signal?)` | 解析搜索提供方并运行一次搜索。在结果上强制执行 `request.maxResults`（截断 `sources[]`，设置 `truncated`）。能力无法运行时抛出 `WebError`。 |
+| `fetch(request, signal?)` | 解析抓取提供方并获取一个 URL。非 2xx 响应是结果，不会抛出异常。无法安全获取或表示资源时抛出 `WebError`。 |
+
+提供方注册的是**能力**而非工具。`dsh-tool-web` 是面向模型的名称、描述、提示词指引、JSON Schema 和呈现的唯一归属方。
+
+## 选择
+
+选择绝不依赖注册、配置或热模块替换（HMR）顺序。能力要么具有显式提供方 id（配置 `searchProvider`／`fetchProvider`，或由环境变量 `$DSH_WEB_SEARCH_PROVIDER`／`$DSH_WEB_FETCH_PROVIDER` 提供相同字段），要么在恰好只注册一个可用提供方时自动选择。`search()`／`fetch()` 会在执行时解析提供方：
+
+| 情况 | 执行 |
+|---|---|
+| 已配置 id 已注册且 `available()` | 运行该提供方 |
+| 已配置 id 未注册 | `WEB_PROVIDER_CONFIGURED_MISSING` |
+| 已配置 id 已注册但不可用 | `WEB_PROVIDER_CONFIGURED_UNAVAILABLE` |
+| 无 id，恰好一个已注册的可用提供方 | 运行该提供方 |
+| 无 id，没有可用提供方 | `WEB_PROVIDER_UNAVAILABLE` |
+| 无 id，多个可用提供方 | `WEB_PROVIDER_AMBIGUOUS` |
+
+失败分支会抛出 `WebError`；调用方按其结构化 code（加消息细节：缺失 id、歧义候选集合）路由。提供方自身的 `available()` 是便宜的局部检查（凭据是否存在、配置是否可解析），供执行时选择使用，且**禁止发起网络调用**；`dsh-tool-web` 永远不会调用它。工具通过 `ctx.web.search()`／`fetch()` 执行，并按抛出的 code 路由，因此提供方选择只有一个归属方。
+
+## 词汇
+
+`WebSearchRequest`（`query`、`maxResults?`）→ `WebSearchResult`（`content?`、`sources[]`、`truncated`）；每个 `WebSearchSource` 都有必填 `url` 与可选 `title`／`snippet`／`publishedAt`（Perplexity 引用可能只含 URL）。`WebFetchRequest`（`url`）→ `WebFetchResult`（最终 `url`、`statusCode`、`body`、`truncated`）；取消作为可选的直接 `AbortSignal` 参数传给 `search()`／`fetch()`。`WebFetchBody` 是这里拥有的封闭判别联合（`html` | `text`）；消费方使用 `switch` 实现穷尽检查，因此新增类型会导致编译失败，直到处理完毕。完整约定见 `src/types.ts`，其中也包含 `WebError` code 分类体系。
+
+## 模型体验
+
+通过 `dsh-tool-web` 间接影响；该工具会保留有界的规范化提供方数据，或者原样保留以下失败：已配置的提供方缺失、提供方不可用、无提供方、存在多个提供方以及 `Error: <message>`；本注册表自身不贡献提示词或 schema。
+
+#### KV Cache 影响
+
+不会直接导致 KV Cache 失效；请求前缀变更由上述消费方负责。
+
+## 已知限制与暂缓事项
+
+- **没有观测接口**：没有提供方变更事件或能力状态查询；可用性只能通过执行 `search()`／`fetch()` 并按抛出的 `WebError` code 路由来观测，无提供方失败是通用的 `WEB_PROVIDER_UNAVAILABLE`，不会枚举逐提供方原因（见 [Agent Note](../../../.agents/notes/archived/simplification/2026-07-04-drop-unconsumed-web-observation-surface.md)）。
+- **`WebSearchRequest` 只携带 `query` + `maxResults`**：提供方无关的控制项（新近程度、域名过滤条件、区域提示、搜索深度）暂缓至 Exa 与 Perplexity 都能诚实支持时（见 [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)）。
+- **`WebFetchBody` 没有 `pdf` 分支**：可提取文本的 PDF 支持属于明确的暂缓工作；封闭联合会使新增该分支成为三个 web 包中由编译强制执行的变更。
+- **提供方支持的页面提取不属于 `fetch()` 范围**：Firecrawl/Tavily 风格的 `web_extract` 能力暂缓，而不会扩展抓取操作。

package/lib/index.js

@@ -0,0 +1,143 @@
+import { Service } from "@deepseek-ai/cordis";
+import z from "@deepseek-ai/schemastery";
+import { HarnessError } from "@deepseek-ai/dsh-llm";
+//#region lib/types/types.js
+/**
+* Vocabulary for the web capability seam (`ctx.web`). Search and fetch deliberately share one
+* seam so provider selection, cancellation, errors, and product configuration have one owner,
+* while retaining separate request and result types.
+* @module @deepseek-ai/dsh-web/types
+*/
+/**
+* Typed web error with a machine-routable, open-string `code` and chained `cause`.
+* Consumers must tolerate provider-specific codes. Shared codes cover unavailable,
+* missing, unusable, ambiguous, or duplicate providers, cancellation, and provider failure;
+* the local fetch provider additionally distinguishes invalid or blocked URLs, redirects,
+* size and timeout limits, and unsupported content types. Tool execution exposes the code in
+* structured error metadata.
+*/
+var WebError = class extends HarnessError {};
+//#endregion
+//#region lib/types/index.js
+/**
+* Service Definition for the web access capability seam (`ctx.web`): registries and provider-selecting execution for search and
+* fetch. Duplicate ids are rejected. At execution time, a configured provider must exist and
+* be usable; without one, exactly one usable provider is required, so selection never depends
+* on registration order.
+* @module @deepseek-ai/dsh-web
+*/
+/**
+* The web access service. Registered as `ctx.web` (one instance per context).
+*
+* Selection semantics (resolved at execution time, never order-dependent):
+* - A configured id that is registered and `available()` → that provider.
+* - A configured id not registered → `WEB_PROVIDER_CONFIGURED_MISSING`.
+* - A configured id registered but unavailable →
+*   `WEB_PROVIDER_CONFIGURED_UNAVAILABLE`.
+* - No id configured, exactly one registered usable provider → that provider.
+* - No id configured, multiple usable providers → `WEB_PROVIDER_AMBIGUOUS`.
+* - No id configured, no usable provider → `WEB_PROVIDER_UNAVAILABLE`.
+*/
+var WebService = class extends Service {
+	/**
+	* Provider selection config. Operational env overrides feed the SAME fields:
+	* `$DSH_WEB_SEARCH_PROVIDER` / `$DSH_WEB_FETCH_PROVIDER` are equivalent to
+	* `searchProvider` / `fetchProvider` and are NOT a hidden priority chain.
+	*/
+	static Config = z.object({
+		searchProvider: z.string(),
+		fetchProvider: z.string()
+	});
+	searchProviders = /* @__PURE__ */ new Map();
+	fetchProviders = /* @__PURE__ */ new Map();
+	searchProviderId;
+	fetchProviderId;
+	constructor(ctx, config = {}) {
+		super(ctx, "web");
+		this.searchProviderId = config.searchProvider ?? process.env.DSH_WEB_SEARCH_PROVIDER;
+		this.fetchProviderId = config.fetchProvider ?? process.env.DSH_WEB_FETCH_PROVIDER;
+	}
+	/**
+	* Register a search provider. Throws {@link WebError} `WEB_DUPLICATE_PROVIDER`
+	* if its id is already registered for search. Returns a disposer; disposed
+	* with the calling fiber.
+	* @param provider - the provider; its `id` is the registry key.
+	* @returns the disposer that unregisters the provider.
+	*/
+	registerSearchProvider(provider) {
+		return this.registerProvider(this.searchProviders, provider);
+	}
+	/**
+	* Register a fetch provider. Throws {@link WebError} `WEB_DUPLICATE_PROVIDER`
+	* if its id is already registered for fetch. Returns a disposer; disposed
+	* with the calling fiber.
+	* @param provider - the provider; its `id` is the registry key.
+	* @returns the disposer that unregisters the provider.
+	*/
+	registerFetchProvider(provider) {
+		return this.registerProvider(this.fetchProviders, provider);
+	}
+	registerProvider(store, provider) {
+		if (store.has(provider.id)) throw new WebError(`a web provider with id "${provider.id}" is already registered`, "WEB_DUPLICATE_PROVIDER");
+		const dispose = this.ctx.effect(function* () {
+			store.set(provider.id, provider);
+			yield () => store.delete(provider.id);
+		}, "web.registerProvider()");
+		return () => void dispose();
+	}
+	/**
+	* Run one search through the selected provider. Resolves the provider at call
+	* time with the selection rules above; throws {@link WebError} when the
+	* capability cannot run. The seam enforces `request.maxResults` on the result:
+	* if the provider over-returns, `sources[]` is truncated and `truncated` set.
+	* @param request - the query and optional result limit.
+	* @param signal - optional cancellation signal forwarded to the provider.
+	* @returns the provider's results, capped to `request.maxResults`.
+	*/
+	async search(request, signal) {
+		return capSources(await resolveProvider({
+			providers: this.searchProviders,
+			...this.searchProviderId !== void 0 ? { configuredId: this.searchProviderId } : {}
+		}).search(request, signal), request.maxResults);
+	}
+	/**
+	* Retrieve one URL through the selected provider. Resolves the provider at
+	* call time with the selection rules above; throws {@link WebError} when the
+	* capability cannot run. A non-2xx response is a result, not a throw.
+	* @param request - the URL plus retrieval options.
+	* @param signal - optional cancellation signal forwarded to the provider.
+	* @returns the retrieval outcome; non-2xx responses resolve descriptively.
+	*/
+	async fetch(request, signal) {
+		return resolveProvider({
+			providers: this.fetchProviders,
+			...this.fetchProviderId !== void 0 ? { configuredId: this.fetchProviderId } : {}
+		}).fetch(request, signal);
+	}
+};
+/** Resolve the selected provider or throw the matching {@link WebError}. */
+function resolveProvider(selection) {
+	const { configuredId, providers } = selection;
+	if (configuredId !== void 0) {
+		const provider = providers.get(configuredId);
+		if (!provider) throw new WebError(`configured web provider "${configuredId}" is not registered`, "WEB_PROVIDER_CONFIGURED_MISSING");
+		if (!provider.available()) throw new WebError(`configured web provider "${configuredId}" is registered but unavailable`, "WEB_PROVIDER_CONFIGURED_UNAVAILABLE");
+		return provider;
+	}
+	const usable = [...providers.values()].filter((provider) => provider.available());
+	const [single] = usable;
+	if (single === void 0) throw new WebError("no usable web provider is registered", "WEB_PROVIDER_UNAVAILABLE");
+	if (usable.length > 1) throw new WebError(`multiple usable web providers are registered (${usable.map((provider) => provider.id).join(", ")}); configure one explicitly`, "WEB_PROVIDER_AMBIGUOUS");
+	return single;
+}
+/** Enforce `maxResults` on a search result: truncate `sources[]` and flag it. */
+function capSources(result, maxResults) {
+	if (maxResults === void 0 || result.sources.length <= maxResults) return result;
+	return {
+		...result,
+		sources: result.sources.slice(0, maxResults),
+		truncated: true
+	};
+}
+//#endregion
+export { WebError, WebService, WebService as default };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-web`.
+* @module @deepseek-ai/dsh-web/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-web";
+/** Cordis companion plugin name. */
+const name = "web-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: provider maps are private and selection/result caps are enforced on each
+* call; the seam publishes no independent registry or request/result observation stream.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Service Definition for the web access capability seam (`ctx.web`): registries and provider-selecting execution for search and
+ * fetch. Duplicate ids are rejected. At execution time, a configured provider must exist and
+ * be usable; without one, exactly one usable provider is required, so selection never depends
+ * on registration order.
+ * @module @deepseek-ai/dsh-web
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { WebFetchProvider, WebFetchRequest, WebFetchResult, WebSearchProvider, WebSearchRequest, WebSearchResult } from './types.ts';
+export { WebError, } from './types.ts';
+export type { WebFetchBody, WebFetchProvider, WebFetchRequest, WebFetchResult, WebSearchProvider, WebSearchRequest, WebSearchResult, WebSearchSource, } from './types.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        web: WebService;
+    }
+}
+/**
+ * Config for the web seam. `searchProvider` / `fetchProvider` pin which provider
+ * wins for each capability; both are optional (a single registered usable
+ * provider auto-selects). Operational overrides such as environment variables
+ * must feed these same fields rather than introduce a hidden priority chain.
+ */
+export interface WebServiceConfig {
+    /** Explicit search provider id. Omitted = auto-select when exactly one usable. */
+    readonly searchProvider?: string;
+    /** Explicit fetch provider id. Omitted = auto-select when exactly one usable. */
+    readonly fetchProvider?: string;
+}
+/**
+ * The web access service. Registered as `ctx.web` (one instance per context).
+ *
+ * Selection semantics (resolved at execution time, never order-dependent):
+ * - A configured id that is registered and `available()` → that provider.
+ * - A configured id not registered → `WEB_PROVIDER_CONFIGURED_MISSING`.
+ * - A configured id registered but unavailable →
+ *   `WEB_PROVIDER_CONFIGURED_UNAVAILABLE`.
+ * - No id configured, exactly one registered usable provider → that provider.
+ * - No id configured, multiple usable providers → `WEB_PROVIDER_AMBIGUOUS`.
+ * - No id configured, no usable provider → `WEB_PROVIDER_UNAVAILABLE`.
+ */
+export declare class WebService extends Service {
+    /**
+     * Provider selection config. Operational env overrides feed the SAME fields:
+     * `$DSH_WEB_SEARCH_PROVIDER` / `$DSH_WEB_FETCH_PROVIDER` are equivalent to
+     * `searchProvider` / `fetchProvider` and are NOT a hidden priority chain.
+     */
+    static Config: z<WebServiceConfig>;
+    private searchProviders;
+    private fetchProviders;
+    private readonly searchProviderId;
+    private readonly fetchProviderId;
+    constructor(ctx: Context, config?: WebServiceConfig);
+    /**
+     * Register a search provider. Throws {@link WebError} `WEB_DUPLICATE_PROVIDER`
+     * if its id is already registered for search. Returns a disposer; disposed
+     * with the calling fiber.
+     * @param provider - the provider; its `id` is the registry key.
+     * @returns the disposer that unregisters the provider.
+     */
+    registerSearchProvider(provider: WebSearchProvider): () => void;
+    /**
+     * Register a fetch provider. Throws {@link WebError} `WEB_DUPLICATE_PROVIDER`
+     * if its id is already registered for fetch. Returns a disposer; disposed
+     * with the calling fiber.
+     * @param provider - the provider; its `id` is the registry key.
+     * @returns the disposer that unregisters the provider.
+     */
+    registerFetchProvider(provider: WebFetchProvider): () => void;
+    private registerProvider;
+    /**
+     * Run one search through the selected provider. Resolves the provider at call
+     * time with the selection rules above; throws {@link WebError} when the
+     * capability cannot run. The seam enforces `request.maxResults` on the result:
+     * if the provider over-returns, `sources[]` is truncated and `truncated` set.
+     * @param request - the query and optional result limit.
+     * @param signal - optional cancellation signal forwarded to the provider.
+     * @returns the provider's results, capped to `request.maxResults`.
+     */
+    search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult>;
+    /**
+     * Retrieve one URL through the selected provider. Resolves the provider at
+     * call time with the selection rules above; throws {@link WebError} when the
+     * capability cannot run. A non-2xx response is a result, not a throw.
+     * @param request - the URL plus retrieval options.
+     * @param signal - optional cancellation signal forwarded to the provider.
+     * @returns the retrieval outcome; non-2xx responses resolve descriptively.
+     */
+    fetch(request: WebFetchRequest, signal?: AbortSignal): Promise<WebFetchResult>;
+}
+export default WebService;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-web`.
+ * @module @deepseek-ai/dsh-web/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "web-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/types.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Vocabulary for the web capability seam (`ctx.web`). Search and fetch deliberately share one
+ * seam so provider selection, cancellation, errors, and product configuration have one owner,
+ * while retaining separate request and result types.
+ * @module @deepseek-ai/dsh-web/types
+ */
+import { HarnessError } from '@deepseek-ai/dsh-llm';
+/**
+ * What one search-capable backend can return. The model-facing argument is just
+ * a query; `maxResults` is a `dsh-tool-web`-layer bound passed through unchanged
+ * and enforced on the way back by the seam (see {@link WebSearchResult}).
+ */
+export interface WebSearchRequest {
+    readonly query: string;
+    /**
+     * Upper bound on returned sources; the seam truncates to it. Omitted = no
+     * bound. `dsh-tool-web` always sets it. A provider whose API supports a
+     * result-count control (Exa's `numResults`) should apply it at the request
+     * layer as a cost/latency optimization; the seam enforces the bound
+     * regardless.
+     */
+    readonly maxResults?: number;
+}
+/**
+ * Normalized search outcome. `content` is optional provider-generated answer
+ * text or summary (Exa and DeepSeek return none; Perplexity returns a
+ * generated answer).
+ * `sources[]` is the portable citation surface. `truncated` is set by the seam
+ * when it cut `sources[]` down to `maxResults`.
+ */
+export interface WebSearchResult {
+    /** Optional provider-generated answer text, search context, or summary. */
+    readonly content?: string;
+    /** Citeable sources, already truncated to the request's `maxResults`. */
+    readonly sources: readonly WebSearchSource[];
+    /** True when the seam dropped sources to honor `maxResults`. */
+    readonly truncated: boolean;
+}
+/**
+ * One citeable source. A source always has a URL; `title`, `snippet`, and
+ * `publishedAt` are optional because not every provider returns them — forcing
+ * adapters to invent them would make the seam lie (Perplexity citations may be
+ * URL-only). `dsh-tool-web` renders `title ?? hostname(url)` for display.
+ */
+export interface WebSearchSource {
+    readonly url: string;
+    readonly title?: string;
+    readonly snippet?: string;
+    /** Publication/crawl timestamp as a provider-supplied ISO-8601 string. */
+    readonly publishedAt?: string;
+}
+/**
+ * What one fetch-capable backend is asked to retrieve. The request deliberately
+ * omits timeout, format, prompt, and extraction controls: cancellation is a
+ * direct execution argument, while presentation and higher-level LLM concerns
+ * belong outside safe retrieval.
+ */
+export interface WebFetchRequest {
+    readonly url: string;
+}
+/**
+ * Normalized fetch outcome. A successful network fetch of a non-2xx response is
+ * a result, not an error: the status code is part of the fetched resource
+ * state. {@link WebError} is reserved for failures to safely retrieve or
+ * represent the resource.
+ */
+export interface WebFetchResult {
+    /** The final URL after allowed redirects (the request URL is in the request). */
+    readonly url: string;
+    /** HTTP status code of the fetched response. */
+    readonly statusCode: number;
+    /** Decoded body, classified by content kind. */
+    readonly body: WebFetchBody;
+    /** True when the provider capped the decoded body. */
+    readonly truncated: boolean;
+}
+/**
+ * The decoded body of a fetched resource. A CLOSED discriminated union owned by
+ * `dsh-web`: the provider decodes the kind and `dsh-tool-web` renders it, so a
+ * new kind is a coordinated change across known packages, not a plugin
+ * extension. Consumers `switch` on `kind` ending in `default: assertNever(...)`
+ * so adding a kind breaks compilation at every consumer until handled. Each arm
+ * stays its own object literal even where fields coincide, so an arm can gain
+ * fields the others lack.
+ */
+export type WebFetchBody = {
+    readonly kind: 'html';
+    readonly content: string;
+} | {
+    readonly kind: 'text';
+    readonly content: string;
+};
+/**
+ * A search-capable backend. Registered with `ctx.web.registerSearchProvider`.
+ * `id` is a stable string, unique within the search capability kind.
+ */
+export interface WebSearchProvider {
+    readonly id: string;
+    /** Cheap local usability check; must not make network calls. */
+    available(): boolean;
+    /** Run one search; honor `signal` for cancellation. */
+    search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult>;
+}
+/**
+ * A fetch-capable backend. Registered with `ctx.web.registerFetchProvider`.
+ * `id` is a stable string, unique within the fetch capability kind.
+ */
+export interface WebFetchProvider {
+    readonly id: string;
+    /** Cheap local usability check; must not make network calls. */
+    available(): boolean;
+    /** Retrieve one URL; honor `signal` for cancellation. */
+    fetch(request: WebFetchRequest, signal?: AbortSignal): Promise<WebFetchResult>;
+}
+/**
+ * Typed web error with a machine-routable, open-string `code` and chained `cause`.
+ * Consumers must tolerate provider-specific codes. Shared codes cover unavailable,
+ * missing, unusable, ambiguous, or duplicate providers, cancellation, and provider failure;
+ * the local fetch provider additionally distinguishes invalid or blocked URLs, redirects,
+ * size and timeout limits, and unsupported content types. Tool execution exposes the code in
+ * structured error metadata.
+ */
+export declare class WebError extends HarnessError {
+}
+//# sourceMappingURL=types.d.ts.map

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@deepseek-ai/dsh-web",
+  "description": "Abstract web access capability seam (ctx.web) for the DeepSeek Harness — search/fetch provider registry, registration-order-independent selection, request/result vocabulary, and the WebError taxonomy",
+  "version": "0.0.1-rc.1",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/web/web"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  }
+}