@truly-private/omdsh-web-fetch-http 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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-fetch-http/README.md
+README.md: 48d3318388f4d3ce74876ac53685744f023908bd
+README.zh.md: 75ae8b7a6fcbe7e990f66089eda9ee2a2b0c7694

package/README.md

@@ -0,0 +1,51 @@
+# @truly-private/omdsh-web-fetch-http
+
+English | [中文](README.zh.md)
+
+An anonymous public HTTP(S) `WebFetchProvider` for the harness [web capability seam](../web/README.md) (`ctx.web`). It retrieves a concrete URL and returns a status code plus bounded decoded content.
+
+This is an **implementation** package: it registers a provider into `ctx.web`, it does not own the key and it does not register a model-facing tool. It is a function/namespace plugin (`inject: ['web']`).
+
+## Responsibility split
+
+The provider owns **safe resource retrieval**: URL validation, HTTP transport, redirect policy, a resource-backstop timeout, abort propagation, byte caps, charset decoding, content-type classification, and binary rejection. `@truly-private/omdsh-tool-web` owns **presentation** (HTML→markdown, truncation formatting). A non-2xx HTTP response is a *result* (status code + decoded body), not an error; `WebError` is reserved for failures to safely retrieve or represent the resource.
+
+The provider's `timeoutMs` is a resource backstop for direct `ctx.web.fetch()` callers and misconfigured deployments, not the model-facing tool-call budget. [`dsh-tool-call-timeout-policy`](../../guard/timeout-policy/README.md) owns the `web_fetch` tool-call budget by arming `exec.signal`.
+
+A shipping web-tool deployment sets the provider backstop above the tool budget, so model calls normally return `TOOL_TIMEOUT`. If the outer deadline reaches the provider first, the provider reports `WEB_ABORTED` and the outer policy replaces it with `TOOL_TIMEOUT`. `WEB_FETCH_TIMEOUT` therefore identifies a direct service caller whose provider budget elapsed.
+
+## Transport hygiene
+
+- Accepts only `http:` and `https:` URLs; rejects credentials in URLs (`WEB_BLOCKED_URL`) and over-long/malformed URLs (`WEB_INVALID_URL`).
+- Enforces a max URL length, response byte cap (`WEB_FETCH_TOO_LARGE`), decoded body character cap, timeout (`WEB_FETCH_TIMEOUT`), and redirect hop cap.
+- Propagates the caller's abort signal (`WEB_ABORTED`) into the network request and the streaming read.
+- Follows only **same-origin** redirects; a cross-origin redirect fails with `WEB_REDIRECT_BLOCKED`, requiring a fresh tool call (the model of Claude Code's WebFetch).
+- Sends an explicit product `User-Agent`, never a browser disguise.
+- Rejects unsupported (e.g. binary) content types with `WEB_UNSUPPORTED_CONTENT_TYPE`.
+
+## Config
+
+| Key | Default | Meaning |
+|---|---|---|
+| `maxUrlLength` | `2048` | Maximum accepted request URL length. |
+| `maxResponseBytes` | `5_000_000` | Maximum response body size in bytes. |
+| `maxBodyChars` | `100_000` | Maximum decoded body length in characters. |
+| `timeoutMs` | `30_000` | Fetch timeout within Node's timer range — a resource backstop for direct `ctx.web.fetch()` callers, not the model-facing tool-call budget (that is `dsh-tool-call-timeout-policy`). |
+| `maxRedirects` | `5` | Maximum same-origin redirect hops (`0` follows none). |
+| `userAgent` | `deepseek-harness/…` | `User-Agent` header. |
+
+The numeric limits are validated at plugin construction: every cap except `maxRedirects` must be a positive finite number, and `maxRedirects` must be a non-negative integer. An invalid value throws rather than silently constructing a provider with nonsensical limits.
+
+## Model Experience
+
+Indirectly, through [`dsh-tool-web`](../tool-web/README.md), which places this provider's `maxBodyChars`-bounded decoded text or markdown-shaped HTML under its fetch-result wrapper and retains provider failures while redirects, headers, and transport mechanics remain hidden.
+
+#### KV Cache effect
+
+No direct invalidation; the named consumer owns any request-prefix changes.
+
+## Known Limitations and Deferred Work
+
+- **SSRF / private-network protection is deferred** — no blocking of private, loopback, link-local, multicast, or otherwise non-public destinations, no DNS-resolve-then-validate, no per-hop re-validation (see [the web capability seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)). Until it lands, this provider is an SSRF primitive and **must not be enabled** in a deployment that can reach sensitive internal network targets.
+- **Only textual content decodes** — html/xhtml and `text/*`-plus-JSON/XML families; a missing `Content-Type` or any binary type throws `WEB_UNSUPPORTED_CONTENT_TYPE`, and text-extractable PDF decoding is named deferred work.
+- **Charset comes only from the `Content-Type` header** (UTF-8 default) — an HTML `<meta charset>` declaration is ignored, and a declared-but-unrecognized charset label throws rather than falling back.

package/README.zh.md

@@ -0,0 +1,51 @@
+# @truly-private/omdsh-web-fetch-http
+
+[English](README.md) | 中文
+
+一个匿名公共 HTTP(S) `WebFetchProvider`，用于 harness [web 能力 seam](../web/README.md)（`ctx.web`）。它获取具体 URL，返回状态码和长度受限的解码内容。
+
+这是一个**实现**包：它向 `ctx.web` 注册提供方，不拥有该键，也不注册面向模型的工具。它是函数／命名空间插件（`inject: ['web']`）。
+
+## 职责拆分
+
+提供方拥有**安全资源获取**：URL 验证、HTTP 传输、重定向策略、资源兜底超时、中止传播、字节上限、charset 解码、内容类型分类与二进制拒绝。`@truly-private/omdsh-tool-web` 拥有**呈现**（HTML→markdown、截断格式）。非 2xx HTTP 响应是*结果*（状态码 + 解码主体），不是错误；`WebError` 只用于无法安全获取或表示资源的失败。
+
+提供方的 `timeoutMs` 是直接 `ctx.web.fetch()` 调用方和配置有误的部署所用的资源兜底，不是面向模型的工具调用预算。[`dsh-tool-call-timeout-policy`](../../guard/timeout-policy/README.md) 拥有 `web_fetch` 工具调用预算，并让 `exec.signal` 在超时时触发，以强制执行该预算。
+
+已交付的 web 工具部署会把提供方兜底设为高于工具预算，因此模型调用通常返回 `TOOL_TIMEOUT`。如果外层截止期限先于提供方的兜底超时触发，提供方会报告 `WEB_ABORTED`，外层策略再将其替换为 `TOOL_TIMEOUT`。因此，`WEB_FETCH_TIMEOUT` 表明直接服务调用方的提供方预算已经耗尽。
+
+## 传输卫生
+
+- 只接受 `http:` 和 `https:` URL；拒绝 URL 中的凭据（`WEB_BLOCKED_URL`）以及过长／格式错误的 URL（`WEB_INVALID_URL`）。
+- 强制执行 URL 最大长度、响应字节上限（`WEB_FETCH_TOO_LARGE`）、解码主体字符上限、超时（`WEB_FETCH_TIMEOUT`）和重定向跳数上限。
+- 把调用方的中止信号（`WEB_ABORTED`）传播到网络请求与流式读取。
+- 只跟随**同源**重定向；跨源重定向以 `WEB_REDIRECT_BLOCKED` 失败，要求发起新的工具调用（沿用 Claude Code 的 WebFetch 模式）。
+- 发送显式的产品 `User-Agent`，绝不伪装成浏览器。
+- 不受支持的内容类型（例如二进制）以 `WEB_UNSUPPORTED_CONTENT_TYPE` 拒绝。
+
+## 配置
+
+| 配置键 | 默认值 | 含义 |
+|---|---|---|
+| `maxUrlLength` | `2048` | 接受的请求 URL 最大长度。 |
+| `maxResponseBytes` | `5_000_000` | 响应主体最大字节数。 |
+| `maxBodyChars` | `100_000` | 解码主体最大字符数。 |
+| `timeoutMs` | `30_000` | Node 定时器范围内的抓取超时：直接 `ctx.web.fetch()` 调用方的资源兜底，而非面向模型的工具调用预算（后者属于 `dsh-tool-call-timeout-policy`）。 |
+| `maxRedirects` | `5` | 同源重定向最大跳数（`0` 表示完全不跟随）。 |
+| `userAgent` | `deepseek-harness/…` | `User-Agent` 标头。 |
+
+数值限制会在插件构造时验证：除 `maxRedirects` 外，每个上限都必须是正的有限数；`maxRedirects` 必须是非负整数。无效值会抛出异常，不会静默构造限制荒谬的提供方。
+
+## 模型体验
+
+通过 [`dsh-tool-web`](../tool-web/README.md) 间接影响；该工具把此提供方经 `maxBodyChars` 限制的解码文本或由 HTML 转换得到的 markdown 置于抓取结果包装层中，并保留提供方失败；重定向、标头与传输机制保持隐藏。
+
+#### KV Cache 影响
+
+不会直接导致 KV Cache 失效；请求前缀变更由上述消费方负责。
+
+## 已知限制与暂缓事项
+
+- **SSRF／私有网络防护暂缓**：不会阻止私有、loopback、link-local、multicast 或其他非公开目标，也不进行 DNS 解析后验证或逐跳重新验证（见 [web 能力 seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md)）。在此功能落地前，该提供方是 SSRF 原语；能够访问敏感内部网络目标的部署**禁止启用它**。
+- **只解码文本内容**：包括 html/xhtml 与 `text/*` 加 JSON/XML 家族；缺少 `Content-Type` 或任何二进制类型都会抛出 `WEB_UNSUPPORTED_CONTENT_TYPE`，可提取文本的 PDF 解码属于明确的暂缓工作。
+- **charset 只来自 `Content-Type` 标头**（默认为 UTF-8）：HTML `<meta charset>` 声明会被忽略；声明但无法识别的 charset 标签会抛出异常，而非回退。

package/lib/index.js

@@ -0,0 +1,415 @@
+import z from "@deepseek-ai/schemastery";
+import { WebError } from "@truly-private/omdsh-web";
+import { deadline, timeoutOf } from "@truly-private/omdsh-timeout";
+//#region lib/types/policy.js
+/**
+* URL validation and content-type classification for the local HTTP(S) fetch
+* provider — the pure, network-free half. The provider's `fetch()` composes
+* these with transport (redirect following, byte caps, decoding).
+*
+* @module @truly-private/omdsh-web-fetch-http/policy
+*/
+/**
+* Validate a request URL against the basic transport hygiene the provider
+* enforces before any network access: http(s) only, no embedded credentials,
+* bounded length. Returns the parsed `URL`. Throws {@link WebError} otherwise.
+* (SSRF / private-network blocking is deferred — see the package Agent Note.)
+*
+* @param input - the raw URL string from the fetch request.
+* @param maxUrlLength - inclusive upper bound on `input`'s length.
+* @returns the parsed `URL`.
+*/
+function validateFetchUrl(input, maxUrlLength) {
+	if (input.length > maxUrlLength) throw new WebError(`URL exceeds the maximum length of ${maxUrlLength}`, "WEB_INVALID_URL");
+	let url;
+	try {
+		url = new URL(input);
+	} catch (error) {
+		throw new WebError(`invalid URL: ${input}`, "WEB_INVALID_URL", { cause: error });
+	}
+	if (url.protocol !== "http:" && url.protocol !== "https:") throw new WebError(`unsupported URL scheme "${url.protocol}" (only http and https are allowed)`, "WEB_INVALID_URL");
+	if (url.username.length > 0 || url.password.length > 0) throw new WebError("credentials in URLs are not allowed", "WEB_BLOCKED_URL");
+	return url;
+}
+/**
+* Two URLs are same-origin when scheme, hostname, and port match. A redirect
+* that crosses origins is refused so each new origin requires a fresh tool call
+* (and thus a fresh provider/permission decision).
+*
+* @param a - one of the two URLs to compare.
+* @param b - the other URL to compare.
+* @returns true when `a` and `b` share scheme, hostname, and port.
+*/
+function isSameOrigin(a, b) {
+	return a.protocol === b.protocol && a.hostname === b.hostname && a.port === b.port;
+}
+/**
+* Classify a response `Content-Type` into a decodable body kind, or `undefined`
+* for an unsupported (e.g. binary) type. `text/html` and `application/xhtml+xml`
+* are `html`; other `text/*` plus a few structured text types are `text`.
+*
+* @param contentType - the raw `Content-Type` header, or `null` when the
+*   response carries none (unsupported).
+* @returns the decodable kind, or `undefined` for an unsupported type.
+*/
+function classifyContentType(contentType) {
+	const mime = (contentType ?? "").replace(/;.*$/s, "").trim().toLowerCase();
+	if (mime === "text/html" || mime === "application/xhtml+xml") return "html";
+	if (mime.startsWith("text/")) return "text";
+	if (mime === "application/json" || mime === "application/xml" || mime.endsWith("+json") || mime.endsWith("+xml")) return "text";
+}
+/**
+* Extract the `charset` parameter from a response `Content-Type`, lower-cased,
+* or `undefined` when absent. The provider feeds this label to `TextDecoder`
+* so a non-UTF-8 response is decoded with its declared encoding rather than
+* silently mangled into replacement characters.
+*
+* @param contentType - the raw `Content-Type` header, or `null` when the
+*   response carries none.
+* @returns the lower-cased charset label, or `undefined` when none is declared.
+*/
+function parseCharset(contentType) {
+	return /;\s*charset\s*=\s*"?([^";]+)"?/i.exec(contentType ?? "")?.[1]?.trim().toLowerCase();
+}
+/**
+* Build a `TextDecoder` for the declared charset, falling back to UTF-8 when
+* none is declared. Throws {@link WebError} `WEB_UNSUPPORTED_CONTENT_TYPE` when
+* the label is present but not a charset `TextDecoder` recognizes — better to
+* fail loudly than return mojibake.
+*
+* @param charset - the declared charset label (from {@link parseCharset}), or
+*   `undefined` to default to UTF-8.
+* @returns a decoder for the declared (or defaulted) encoding.
+*/
+function decoderForCharset(charset) {
+	if (charset === void 0) return new TextDecoder("utf-8");
+	try {
+		return new TextDecoder(charset);
+	} catch (error) {
+		throw new WebError(`unsupported charset "${charset}"`, "WEB_UNSUPPORTED_CONTENT_TYPE", { cause: error });
+	}
+}
+//#endregion
+//#region lib/types/provider.js
+/**
+* Safe HTTP(S) retrieval for `ctx.web`: validates URLs, follows only same-origin redirects,
+* enforces time and size limits, classifies and decodes text, and leaves presentation to
+* `@truly-private/omdsh-tool-web`. Requests carry no browser cookies or ambient credentials.
+*
+* Private-network and SSRF protection is not implemented; do not enable this provider where
+* it can reach sensitive internal targets.
+* @module @truly-private/omdsh-web-fetch-http/provider
+*/
+var __addDisposableResource = function(env, value, async) {
+	if (value !== null && value !== void 0) {
+		if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+		var dispose, inner;
+		if (async) {
+			if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+			dispose = value[Symbol.asyncDispose];
+		}
+		if (dispose === void 0) {
+			if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+			dispose = value[Symbol.dispose];
+			if (async) inner = dispose;
+		}
+		if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+		if (inner) dispose = function() {
+			try {
+				inner.call(this);
+			} catch (e) {
+				return Promise.reject(e);
+			}
+		};
+		env.stack.push({
+			value,
+			dispose,
+			async
+		});
+	} else if (async) env.stack.push({ async: true });
+	return value;
+};
+var __disposeResources = (function(SuppressedError) {
+	return function(env) {
+		function fail(e) {
+			env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+			env.hasError = true;
+		}
+		var r, s = 0;
+		function next() {
+			while (r = env.stack.pop()) try {
+				if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+				if (r.dispose) {
+					var result = r.dispose.call(r.value);
+					if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) {
+						fail(e);
+						return next();
+					});
+				} else s |= 1;
+			} catch (e) {
+				fail(e);
+			}
+			if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+			if (env.hasError) throw env.error;
+		}
+		return next();
+	};
+})(typeof SuppressedError === "function" ? SuppressedError : function(error, suppressed, message) {
+	var e = new Error(message);
+	return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+/** Stable id this provider registers under. */
+const LOCAL_FETCH_PROVIDER_ID = "http";
+/** The anonymous public HTTP(S) fetch provider. */
+var HttpFetchProvider = class {
+	limits;
+	id = LOCAL_FETCH_PROVIDER_ID;
+	constructor(limits) {
+		this.limits = limits;
+	}
+	/** No credentials to check — an anonymous public fetcher is always usable. */
+	available() {
+		return true;
+	}
+	async fetch(request, signal) {
+		const env_1 = {
+			stack: [],
+			error: void 0,
+			hasError: false
+		};
+		try {
+			if (signal?.aborted) throw new WebError("web fetch aborted", "WEB_ABORTED");
+			const d = __addDisposableResource(env_1, deadline(signal, this.limits.timeoutMs, "WEB_FETCH_TIMEOUT"), false);
+			return await this.followAndRead(request.url, d.signal);
+		} catch (e_1) {
+			env_1.error = e_1;
+			env_1.hasError = true;
+		} finally {
+			__disposeResources(env_1);
+		}
+	}
+	/** Follow same-origin redirects up to the hop cap, then read the final response. */
+	async followAndRead(initialUrl, signal) {
+		let currentUrl = validateFetchUrl(initialUrl, this.limits.maxUrlLength);
+		let redirectsFollowed = 0;
+		for (;;) {
+			const response = await this.requestOnce(currentUrl, signal);
+			if (isRedirectStatus(response.status)) {
+				if (redirectsFollowed >= this.limits.maxRedirects) {
+					await response.body?.cancel();
+					throw new WebError(`exceeded the maximum of ${this.limits.maxRedirects} redirects`, "WEB_REDIRECT_BLOCKED");
+				}
+				const location = response.headers.get("location");
+				if (location === null) {
+					await response.body?.cancel();
+					throw new WebError(`redirect response (HTTP ${response.status}) without a Location header`, "WEB_PROVIDER_ERROR");
+				}
+				const target = resolveRedirect(location, currentUrl);
+				let validatedTarget;
+				try {
+					validatedTarget = validateFetchUrl(target.toString(), this.limits.maxUrlLength);
+					if (!isSameOrigin(validatedTarget, currentUrl)) throw new WebError(`cross-origin redirect to ${validatedTarget.origin} is not followed automatically; retry against that URL directly`, "WEB_REDIRECT_BLOCKED");
+				} catch (error) {
+					await response.body?.cancel();
+					throw error;
+				}
+				await response.body?.cancel();
+				currentUrl = validatedTarget;
+				redirectsFollowed++;
+				continue;
+			}
+			return await this.readBody(response, currentUrl, signal);
+		}
+	}
+	async requestOnce(url, signal) {
+		try {
+			return await fetch(url, {
+				method: "GET",
+				redirect: "manual",
+				headers: {
+					"user-agent": this.limits.userAgent,
+					"accept": "text/html,application/xhtml+xml,text/*;q=0.9,application/json;q=0.8"
+				},
+				signal
+			});
+		} catch (error) {
+			throw translateAbortOrNetwork(error, signal);
+		}
+	}
+	/** Read, byte-cap, classify, and decode the final response body. */
+	async readBody(response, finalUrl, signal) {
+		const contentType = response.headers.get("content-type");
+		const kind = classifyContentType(contentType);
+		if (kind === void 0) {
+			await response.body?.cancel();
+			throw new WebError(`unsupported content type "${contentType ?? "unknown"}"`, "WEB_UNSUPPORTED_CONTENT_TYPE");
+		}
+		let decoder;
+		try {
+			decoder = decoderForCharset(parseCharset(contentType));
+		} catch (error) {
+			await response.body?.cancel();
+			throw error;
+		}
+		const { bytes, truncatedByBytes } = await this.readCapped(response, signal);
+		const decoded = decoder.decode(bytes);
+		const truncatedByChars = decoded.length > this.limits.maxBodyChars;
+		const content = truncatedByChars ? decoded.slice(0, this.limits.maxBodyChars) : decoded;
+		const body = kind === "html" ? {
+			kind: "html",
+			content
+		} : {
+			kind: "text",
+			content
+		};
+		return {
+			url: finalUrl.toString(),
+			statusCode: response.status,
+			body,
+			truncated: truncatedByBytes || truncatedByChars
+		};
+	}
+	/**
+	* Read the response stream up to `maxResponseBytes`. A `Content-Length` over
+	* the cap rejects immediately with `WEB_FETCH_TOO_LARGE`; a stream that grows
+	* past the cap is cut short (`truncatedByBytes`) rather than rejected, so a
+	* server that under-reports still yields a bounded usable body.
+	*/
+	async readCapped(response, signal) {
+		const declared = response.headers.get("content-length");
+		if (declared !== null) {
+			const length = Number(declared);
+			if (Number.isFinite(length) && length > this.limits.maxResponseBytes) {
+				await response.body?.cancel();
+				throw new WebError(`response exceeds the maximum of ${this.limits.maxResponseBytes} bytes`, "WEB_FETCH_TOO_LARGE");
+			}
+		}
+		/* v8 ignore next -- a 2xx Response from fetch always exposes a body stream; the null guard is defensive. */
+		if (response.body === null) return {
+			bytes: new Uint8Array(0),
+			truncatedByBytes: false
+		};
+		const chunks = [];
+		let total = 0;
+		let truncatedByBytes = false;
+		const reader = response.body.getReader();
+		try {
+			for (;;) {
+				const { done, value } = await reader.read();
+				if (done) break;
+				const remaining = this.limits.maxResponseBytes - total;
+				if (value.byteLength > remaining) {
+					chunks.push(value.subarray(0, remaining));
+					total += remaining;
+					truncatedByBytes = true;
+					break;
+				}
+				chunks.push(value);
+				total += value.byteLength;
+			}
+		} catch (error) {
+			/* v8 ignore next -- mid-stream read fault needs a network drop after headers; translate path covered by request-phase tests. */
+			throw translateAbortOrNetwork(error, signal);
+		} finally {
+			/* v8 ignore next 4 -- cancel() after a completed/broken read settles without rejecting; unobserved best-effort cleanup. */
+			await reader.cancel().catch(() => {});
+		}
+		const bytes = new Uint8Array(total);
+		let offset = 0;
+		for (const chunk of chunks) {
+			bytes.set(chunk, offset);
+			offset += chunk.byteLength;
+		}
+		return {
+			bytes,
+			truncatedByBytes
+		};
+	}
+};
+/** HTTP redirect status codes that carry a `Location`. */
+function isRedirectStatus(status) {
+	return status === 301 || status === 302 || status === 303 || status === 307 || status === 308;
+}
+/** Resolve a (possibly relative) `Location` against the current URL. */
+function resolveRedirect(location, base) {
+	try {
+		return new URL(location, base);
+	} catch (error) {
+		/* v8 ignore next 2 -- URL resolution against a valid absolute base effectively never throws; defensive guard. */
+		throw new WebError(`invalid redirect Location "${location}"`, "WEB_PROVIDER_ERROR", { cause: error });
+	}
+}
+/**
+* Translate a thrown fetch/stream error into a `WebError`, classified by the
+* deadline signal rather than the thrown value (which differs by phase: the
+* request-phase `fetch` rejects with the abort reason, while the read-phase
+* reader surfaces a bare `AbortError`). `timeoutOf(signal, 'WEB_FETCH_TIMEOUT')`
+* recovering OUR reason means our timeout fired (`WEB_FETCH_TIMEOUT`); any other
+* abort — an upstream cancel, or a foreign/outer deadline's timeout under
+* nesting — is `WEB_ABORTED`; a throw with the signal NOT aborted is a
+* transport/network failure (`WEB_PROVIDER_ERROR`).
+*/
+function translateAbortOrNetwork(error, signal) {
+	const timeout = timeoutOf(signal, "WEB_FETCH_TIMEOUT");
+	if (timeout !== void 0) return new WebError("web fetch timed out", "WEB_FETCH_TIMEOUT", { cause: timeout });
+	if (signal.aborted) return new WebError("web fetch aborted", "WEB_ABORTED", { cause: error });
+	return new WebError(`web fetch failed: ${String(error)}`, "WEB_PROVIDER_ERROR", { cause: error });
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* `@truly-private/omdsh-web-fetch-http`: registers an anonymous public HTTP(S)
+* `WebFetchProvider` with `ctx.web`. A function/namespace plugin (NOT a
+* default-export service): it registers INTO the seam's fetch registry, like the
+* search providers register into the search registry.
+*
+* @module @truly-private/omdsh-web-fetch-http
+*/
+const MAX_NODE_TIMER_DELAY_MS = 2147483647;
+/** Default `User-Agent`: an explicit product agent, never a browser disguise. */
+const DEFAULT_USER_AGENT = "deepseek-harness/0.0.1 (+https://github.com/deepseek-ai)";
+/** Cordis plugin name used by loader diagnostics. */
+const name = "web-fetch-http";
+/** The web seam this provider registers into. */
+const inject = ["web"];
+const Config = z.object({
+	maxUrlLength: z.number().default(2048),
+	maxResponseBytes: z.number().default(5e6),
+	maxBodyChars: z.number().default(1e5),
+	timeoutMs: z.number().default(3e4),
+	maxRedirects: z.number().default(5),
+	userAgent: z.string().default(DEFAULT_USER_AGENT)
+});
+/** A resource limit (byte/char/length/timeout cap) must be a positive finite number. */
+function assertPositiveFinite(name, value) {
+	if (!Number.isFinite(value) || value <= 0) throw new Error(`web-fetch-http: ${name} must be a positive finite number`);
+}
+/** Node coerces larger timer delays to 1 ms, so reject them at configuration time. */
+function assertTimeoutMs(value) {
+	assertPositiveFinite("timeoutMs", value);
+	if (value > MAX_NODE_TIMER_DELAY_MS) throw new Error(`web-fetch-http: timeoutMs must be no greater than ${MAX_NODE_TIMER_DELAY_MS}`);
+}
+/** The redirect hop cap must be a non-negative integer (0 follows no redirects). */
+function assertNonNegativeInteger(name, value) {
+	if (!Number.isInteger(value) || value < 0) throw new Error(`web-fetch-http: ${name} must be a non-negative integer`);
+}
+/** Register the local HTTP(S) fetch provider with `ctx.web`. */
+function apply(ctx, config) {
+	const resolved = config;
+	assertPositiveFinite("maxUrlLength", resolved.maxUrlLength);
+	assertPositiveFinite("maxResponseBytes", resolved.maxResponseBytes);
+	assertPositiveFinite("maxBodyChars", resolved.maxBodyChars);
+	assertTimeoutMs(resolved.timeoutMs);
+	assertNonNegativeInteger("maxRedirects", resolved.maxRedirects);
+	const limits = {
+		maxUrlLength: resolved.maxUrlLength,
+		maxResponseBytes: resolved.maxResponseBytes,
+		maxBodyChars: resolved.maxBodyChars,
+		timeoutMs: resolved.timeoutMs,
+		maxRedirects: resolved.maxRedirects,
+		userAgent: resolved.userAgent
+	};
+	ctx.web.registerFetchProvider(new HttpFetchProvider(limits));
+}
+//#endregion
+export { Config, DEFAULT_USER_AGENT, HttpFetchProvider, LOCAL_FETCH_PROVIDER_ID, apply, inject, name };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@truly-private/omdsh-web-fetch-http`.
+* @module @truly-private/omdsh-web-fetch-http/invariant
+*/
+const PACKAGE_NAME = "@truly-private/omdsh-web-fetch-http";
+/** Cordis companion plugin name. */
+const name = "web-fetch-http-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this package exposes no independent event sequence or mutable data relation
+* beyond contracts enforced at its owning seam.
+*/
+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,37 @@
+/**
+ * `@truly-private/omdsh-web-fetch-http`: registers an anonymous public HTTP(S)
+ * `WebFetchProvider` with `ctx.web`. A function/namespace plugin (NOT a
+ * default-export service): it registers INTO the seam's fetch registry, like the
+ * search providers register into the search registry.
+ *
+ * @module @truly-private/omdsh-web-fetch-http
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+export { LOCAL_FETCH_PROVIDER_ID, HttpFetchProvider, } from './provider.ts';
+export type { HttpFetchLimits } from './provider.ts';
+/** Default `User-Agent`: an explicit product agent, never a browser disguise. */
+export declare const DEFAULT_USER_AGENT = "deepseek-harness/0.0.1 (+https://github.com/deepseek-ai)";
+/** Cordis plugin name used by loader diagnostics. */
+export declare const name = "web-fetch-http";
+/** The web seam this provider registers into. */
+export declare const inject: string[];
+/** Plugin config: the provider's transport and size limits plus its `User-Agent` (all defaulted). */
+export interface Config {
+    /** Maximum accepted request URL length. */
+    maxUrlLength?: number;
+    /** Maximum response body size in bytes. */
+    maxResponseBytes?: number;
+    /** Maximum decoded body length in characters. */
+    maxBodyChars?: number;
+    /** Default fetch timeout in milliseconds, within Node's timer range. */
+    timeoutMs?: number;
+    /** Maximum number of same-origin redirect hops to follow. */
+    maxRedirects?: number;
+    /** `User-Agent` header sent on every request. */
+    userAgent?: string;
+}
+export declare const Config: z<Config>;
+/** Register the local HTTP(S) fetch provider with `ctx.web`. */
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@truly-private/omdsh-web-fetch-http`.
+ * @module @truly-private/omdsh-web-fetch-http/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "web-fetch-http-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/policy.d.ts

@@ -0,0 +1,63 @@
+/**
+ * URL validation and content-type classification for the local HTTP(S) fetch
+ * provider — the pure, network-free half. The provider's `fetch()` composes
+ * these with transport (redirect following, byte caps, decoding).
+ *
+ * @module @truly-private/omdsh-web-fetch-http/policy
+ */
+/** The body kinds this provider decodes. */
+export type FetchableKind = 'html' | 'text';
+/**
+ * Validate a request URL against the basic transport hygiene the provider
+ * enforces before any network access: http(s) only, no embedded credentials,
+ * bounded length. Returns the parsed `URL`. Throws {@link WebError} otherwise.
+ * (SSRF / private-network blocking is deferred — see the package Agent Note.)
+ *
+ * @param input - the raw URL string from the fetch request.
+ * @param maxUrlLength - inclusive upper bound on `input`'s length.
+ * @returns the parsed `URL`.
+ */
+export declare function validateFetchUrl(input: string, maxUrlLength: number): URL;
+/**
+ * Two URLs are same-origin when scheme, hostname, and port match. A redirect
+ * that crosses origins is refused so each new origin requires a fresh tool call
+ * (and thus a fresh provider/permission decision).
+ *
+ * @param a - one of the two URLs to compare.
+ * @param b - the other URL to compare.
+ * @returns true when `a` and `b` share scheme, hostname, and port.
+ */
+export declare function isSameOrigin(a: URL, b: URL): boolean;
+/**
+ * Classify a response `Content-Type` into a decodable body kind, or `undefined`
+ * for an unsupported (e.g. binary) type. `text/html` and `application/xhtml+xml`
+ * are `html`; other `text/*` plus a few structured text types are `text`.
+ *
+ * @param contentType - the raw `Content-Type` header, or `null` when the
+ *   response carries none (unsupported).
+ * @returns the decodable kind, or `undefined` for an unsupported type.
+ */
+export declare function classifyContentType(contentType: string | null): FetchableKind | undefined;
+/**
+ * Extract the `charset` parameter from a response `Content-Type`, lower-cased,
+ * or `undefined` when absent. The provider feeds this label to `TextDecoder`
+ * so a non-UTF-8 response is decoded with its declared encoding rather than
+ * silently mangled into replacement characters.
+ *
+ * @param contentType - the raw `Content-Type` header, or `null` when the
+ *   response carries none.
+ * @returns the lower-cased charset label, or `undefined` when none is declared.
+ */
+export declare function parseCharset(contentType: string | null): string | undefined;
+/**
+ * Build a `TextDecoder` for the declared charset, falling back to UTF-8 when
+ * none is declared. Throws {@link WebError} `WEB_UNSUPPORTED_CONTENT_TYPE` when
+ * the label is present but not a charset `TextDecoder` recognizes — better to
+ * fail loudly than return mojibake.
+ *
+ * @param charset - the declared charset label (from {@link parseCharset}), or
+ *   `undefined` to default to UTF-8.
+ * @returns a decoder for the declared (or defaulted) encoding.
+ */
+export declare function decoderForCharset(charset: string | undefined): TextDecoder;
+//# sourceMappingURL=policy.d.ts.map

package/lib/types/provider.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Safe HTTP(S) retrieval for `ctx.web`: validates URLs, follows only same-origin redirects,
+ * enforces time and size limits, classifies and decodes text, and leaves presentation to
+ * `@truly-private/omdsh-tool-web`. Requests carry no browser cookies or ambient credentials.
+ *
+ * Private-network and SSRF protection is not implemented; do not enable this provider where
+ * it can reach sensitive internal targets.
+ * @module @truly-private/omdsh-web-fetch-http/provider
+ */
+import type { WebFetchProvider, WebFetchRequest, WebFetchResult } from '@truly-private/omdsh-web';
+/** Resolved provider limits (the plugin's schemastery Config supplies defaults). */
+export interface HttpFetchLimits {
+    /** Maximum accepted request URL length. */
+    maxUrlLength: number;
+    /** Maximum response body size in bytes (read is aborted past this). */
+    maxResponseBytes: number;
+    /** Maximum decoded body length in characters (truncated past this). */
+    maxBodyChars: number;
+    /** Default fetch timeout in milliseconds. */
+    timeoutMs: number;
+    /** Maximum number of (same-origin) redirect hops to follow. */
+    maxRedirects: number;
+    /** `User-Agent` header sent on every request. */
+    userAgent: string;
+}
+/** Stable id this provider registers under. */
+export declare const LOCAL_FETCH_PROVIDER_ID = "http";
+/** The anonymous public HTTP(S) fetch provider. */
+export declare class HttpFetchProvider implements WebFetchProvider {
+    private readonly limits;
+    readonly id = "http";
+    constructor(limits: HttpFetchLimits);
+    /** No credentials to check — an anonymous public fetcher is always usable. */
+    available(): boolean;
+    fetch(request: WebFetchRequest, signal?: AbortSignal): Promise<WebFetchResult>;
+    /** Follow same-origin redirects up to the hop cap, then read the final response. */
+    private followAndRead;
+    private requestOnce;
+    /** Read, byte-cap, classify, and decode the final response body. */
+    private readBody;
+    /**
+     * Read the response stream up to `maxResponseBytes`. A `Content-Length` over
+     * the cap rejects immediately with `WEB_FETCH_TOO_LARGE`; a stream that grows
+     * past the cap is cut short (`truncatedByBytes`) rather than rejected, so a
+     * server that under-reports still yields a bounded usable body.
+     */
+    private readCapped;
+}
+//# sourceMappingURL=provider.d.ts.map

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@truly-private/omdsh-web-fetch-http",
+  "description": "Anonymous public HTTP(S) fetch provider for the DeepSeek Harness web capability seam (ctx.web)",
+  "version": "0.0.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Truly-Private/oh-my-deepseek-harness.git",
+    "directory": "packages/web/web-fetch-http"
+  },
+  "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": "MIT",
+  "peerDependencies": {
+    "@truly-private/omdsh-invariants": "^0.0.1",
+    "@truly-private/omdsh-timeout": "^0.0.1",
+    "@truly-private/omdsh-web": "^0.0.1",
+    "@deepseek-ai/cordis": "^4.0.1"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "devDependencies": {
+    "@truly-private/omdsh-timeout": "^0.0.1",
+    "@truly-private/omdsh-web": "^0.0.1",
+    "@truly-private/omdsh-invariants": "^0.0.1",
+    "@deepseek-ai/cordis": "^4.0.1"
+  }
+}