@hydraharness/harness-web 0.1.1-rc.10

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

@@ -0,0 +1,73 @@
+# @hydraharness/harness-web
+
+The **`WebRuntime`** (`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 shell/fs it spans two operations (search and fetch) on one seam, with potentially multiple providers each:
+
+| Package | Role |
+|---|---|
+| `@hydraharness/harness-web` (this) | Service Definition: the service, provider registries, selection policy, request/result vocabulary, the `WebError` taxonomy |
+| `@hydraharness/harness-web-search-exa` | Search provider: Exa |
+| `@hydraharness/harness-web-search-perplexity` | Search provider: Perplexity |
+| `@hydraharness/harness-web-fetch-http` | Fetch provider: anonymous public HTTP(S) |
+| `@hydraharness/harness-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. `@hydraharness/harness-tool-web` is the only owner of model-facing names, descriptions, prompt guidance, JSON schemas, and presentation.
+
+## Product search settings
+
+The base bundle sets `requireSearchSelection: true`. The `web-search` namespace stores `enabled` (true), `provider` (empty), `maxQueries` (4), `maxResults` (8), and `timeoutMs` (60000). Empty selection and disabled search fail as `CONFIG_ERROR`. Provider selection is independent of chat and takes effect on the next call. Product mode never runs fallback providers.
+
+An explicit legacy DeepSeek search section initializes the selected provider to `deepseek-official`; an existing chat credential alone does not. The initialized empty selection is persisted so configuring a provider later does not trigger migration. An explicit composition `searchProvider` seeds selection. Read-only settings retain the composition choice and cannot persist migration.
+
+Providers optionally declare a descriptor with supported search types, a settings namespace, a credential reference, and control metadata. `listSearchProviders()` feeds Settings; `testSearchProvider()` executes a small real query against saved configuration. DeepSeek, Serper, and Other advertise only web search. Exa and Perplexity remain available to explicit compositions, without MVP Settings controls.
+
+Product search failures expose `SearchProviderError`: provider id, safe message, retryable flag, optional HTTP status, and one of `AUTH_ERROR`, `RATE_LIMITED`, `TIMEOUT`, `NETWORK_ERROR`, `INVALID_RESPONSE`, `CONFIG_ERROR`, or `UNKNOWN`. Logs contain provider, query count, duration, normalized result count, status, retries, and category. Credentials and upstream exception text are excluded.
+
+Normalized sources retain optional provider, position, and score. Duplicate comparison removes fragments and common tracking parameters. URL parsing normalizes host spelling, default ports, and root slashes; non-root trailing slashes remain distinct because servers may serve different resources. The tool merges query results in rank order and applies the total cap.
+
+## Standalone selection
+
+Selection never depends on registration, config, or HMR order. Search and fetch use their own explicit provider ids (config `searchProvider`/`fetchProvider`, or env `$HYDRA_WEB_SEARCH_PROVIDER`/`$HYDRA_WEB_FETCH_PROVIDER` feeding the same fields), or auto-select when exactly one usable provider is registered. The active LLM provider does not participate in web-provider selection. `search()`/`fetch()` resolve 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 direct 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**; `@hydraharness/harness-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.
+
+`searchFallbackProviders` optionally lists backups for an explicit `searchProvider`. The complete chain must name registered, distinct providers. Each provider runs at most once under the same caller signal. Provider availability, credentials, and provider failures may advance the chain; cancellation, destination denial, configuration errors, and non-WebError exceptions do not. Empty results are successful. The default chain is empty.
+
+## Model Experience
+
+Indirectly, through `@hydraharness/harness-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
+
+- Provider descriptors describe configuration and implemented search types; credential status remains owned by the credentials subsystem.
+- Domain filtering and provider-specific search depth remain outside the common request.
+- **`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/lib/index.js

@@ -0,0 +1,347 @@
+import { Service } from "@hydraharness/cordis";
+import z from "@hydraharness/schemastery";
+import { installSettingsSection, settingsNamespace } from "@hydraharness/harness-settings";
+import { HarnessError } from "@hydraharness/harness-llm";
+//#region lib/types/settings.js
+/** Product search selection and invocation limits, independent of chat configuration. */
+/** Schema shared by registration and composition default resolution. */
+const SearchSettings = z.object({
+	enabled: z.boolean().default(true),
+	provider: z.string().default(""),
+	maxQueries: z.number().step(1).min(1).max(100).default(4),
+	maxResults: z.number().step(1).min(1).max(100).default(8),
+	timeoutMs: z.number().step(1).min(1).max(6e5).default(6e4)
+});
+//#endregion
+//#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 @hydraharness/harness-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/search.js
+/** Shared search errors, provider configuration metadata, and URL normalization. */
+/** Web-only capabilities; endpoints for other search types are not advertised. */
+const WEB_SEARCH_CAPABILITIES = {
+	web: true,
+	images: false,
+	news: false,
+	videos: false,
+	academic: false
+};
+const messages = {
+	AUTH_ERROR: "Authentication failed. Replace the API key in Settings > Web Search.",
+	RATE_LIMITED: "Provider quota or rate limit exceeded (HTTP 429).",
+	TIMEOUT: "Search connection timed out.",
+	NETWORK_ERROR: "Could not connect to the search provider.",
+	INVALID_RESPONSE: "Search response format is incompatible with the configured mapping.",
+	CONFIG_ERROR: "Configure the provider and its credential in Settings > Web Search.",
+	UNKNOWN: "Search provider failed."
+};
+/** Search failure containing only owned diagnostics, never upstream text or causes. */
+var SearchProviderError = class extends WebError {
+	provider;
+	code;
+	statusCode;
+	/** Whether a later retry may succeed without reconfiguration. */
+	retryable;
+	constructor(provider, code, statusCode, message = messages[code]) {
+		super(message, code);
+		this.provider = provider;
+		this.code = code;
+		this.statusCode = statusCode;
+		this.retryable = [
+			"RATE_LIMITED",
+			"TIMEOUT",
+			"NETWORK_ERROR"
+		].includes(code);
+	}
+};
+/**
+* Translate an HTTP failure without reading an untrusted error body.
+* @param provider - registered provider id.
+* @param status - HTTP status.
+* @returns the normalized failure.
+*/
+function searchHttpError(provider, status) {
+	return new SearchProviderError(provider, status === 401 || status === 403 ? "AUTH_ERROR" : status === 429 ? "RATE_LIMITED" : status >= 500 ? "NETWORK_ERROR" : "CONFIG_ERROR", status);
+}
+/**
+* Remove fragments and common tracking parameters for duplicate detection.
+* Non-root trailing slashes and meaningful query parameters remain distinct.
+* @param value - source URL.
+* @returns a canonical comparison key, or the unchanged malformed URL.
+*/
+function normalizedSearchUrl(value) {
+	try {
+		const url = new URL(value);
+		url.hash = "";
+		for (const key of [...url.searchParams.keys()]) if (/^(utm_.+|fbclid|gclid|dclid|msclkid)$/i.test(key)) url.searchParams.delete(key);
+		return url.href;
+	} catch {
+		return value;
+	}
+}
+//#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 @hydraharness/harness-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 WebRuntime = class extends Service {
+	/**
+	* Provider selection config. Operational env overrides feed the SAME fields:
+	* `$HYDRA_WEB_SEARCH_PROVIDER` / `$HYDRA_WEB_FETCH_PROVIDER` are equivalent to
+	* `searchProvider` / `fetchProvider` and are NOT a hidden priority chain.
+	*/
+	static Config = z.object({
+		requireSearchSelection: z.boolean().default(false),
+		searchProvider: z.string(),
+		fetchProvider: z.string(),
+		searchFallbackProviders: z.array(z.string()).default([])
+	});
+	searchProviders = /* @__PURE__ */ new Map();
+	fetchProviders = /* @__PURE__ */ new Map();
+	searchProviderId;
+	fetchProviderId;
+	searchFallbackProviders;
+	searchSettings;
+	requireSearchSelection;
+	constructor(ctx, config = {}) {
+		super(ctx, "web");
+		this.searchProviderId = config.searchProvider ?? process.env.HYDRA_WEB_SEARCH_PROVIDER;
+		this.fetchProviderId = config.fetchProvider ?? process.env.HYDRA_WEB_FETCH_PROVIDER;
+		this.searchFallbackProviders = [...config.searchFallbackProviders ?? []];
+		this.requireSearchSelection = config.requireSearchSelection === true;
+		const settings = SearchSettings({ provider: this.searchProviderId ?? "" });
+		this.searchSettings = () => settings;
+		installSettingsSection(ctx, settingsNamespace("web-search"), SearchSettings, settings, {
+			setSource: (source) => {
+				this.searchSettings = source;
+			},
+			onChange: () => {}
+		});
+		if (this.searchFallbackProviders.length > 0 && this.searchProviderId === void 0) throw new WebError("searchFallbackProviders requires an explicit searchProvider", "WEB_PROVIDER_CONFIGURED_MISSING");
+		const chain = [this.searchProviderId, ...this.searchFallbackProviders];
+		if (new Set(chain).size !== chain.length || this.searchFallbackProviders.some((id) => id.trim() === "")) throw new WebError("searchFallbackProviders must contain distinct non-empty provider ids excluding the primary", "WEB_DUPLICATE_PROVIDER");
+	}
+	/**
+	* Read current product limits; standalone compositions retain tool-level limits.
+	* @returns saved invocation preferences when product selection is enabled.
+	*/
+	searchPreferences() {
+		return this.requireSearchSelection ? this.searchSettings() : void 0;
+	}
+	/**
+	* List provider-owned, secret-free Settings descriptors.
+	* @returns configurable providers in registration order.
+	*/
+	listSearchProviders() {
+		return [...this.searchProviders.values()].flatMap((provider) => provider.descriptor === void 0 ? [] : [provider.descriptor]);
+	}
+	/**
+	* Persist the first search selection from explicit legacy configuration only.
+	* An explicit empty selection also marks a fresh installation as initialized.
+	* @param provider - legacy registered id.
+	* @param configured - whether a legacy search section contains explicit settings.
+	*/
+	async migrateSearchSelection(provider, configured) {
+		const settings = this.ctx.get("settings");
+		if (!this.requireSearchSelection || settings === void 0) return;
+		const ns = settingsNamespace("web-search");
+		const descriptor = settings.describe().find((item) => item.ns === ns);
+		if (descriptor === void 0 || Object.hasOwn(descriptor.user ?? {}, "provider")) return;
+		if (!settings.writable) return;
+		await settings.update(ns, { provider: this.searchProviderId ?? (configured ? provider : "") }, descriptor.revision);
+	}
+	/**
+	* Execute a small real search with a saved provider without changing selection.
+	* @param id - registered provider to test.
+	* @param signal - caller cancellation.
+	* @returns normalized results after validating the provider response.
+	*/
+	async testSearchProvider(id, signal) {
+		return this.runSearchProvider(id, {
+			query: "Hydra search provider connectivity test",
+			maxResults: 5
+		}, signal);
+	}
+	async runSearchProvider(id, request, signal) {
+		const provider = this.searchProviders.get(id);
+		if (provider === void 0 || !provider.available()) throw new SearchProviderError(id, "CONFIG_ERROR");
+		const type = request.type ?? "web";
+		if (!(provider.descriptor?.capabilities[type] ?? type === "web")) throw new SearchProviderError(id, "CONFIG_ERROR", void 0, `Provider "${id}" does not support ${type} search.`);
+		const timeout = AbortSignal.timeout(this.searchSettings().timeoutMs);
+		const boundedSignal = signal === void 0 ? timeout : AbortSignal.any([signal, timeout]);
+		const started = Date.now();
+		let result;
+		let failure;
+		try {
+			const raw = await provider.search(request, boundedSignal);
+			const seen = /* @__PURE__ */ new Set();
+			const sources = raw.sources.filter((source) => {
+				const key = normalizedSearchUrl(source.url);
+				if (seen.has(key)) return false;
+				seen.add(key);
+				return true;
+			}).map((source) => ({
+				...source,
+				provider: id
+			}));
+			result = capSources({
+				...raw,
+				sources,
+				provider: id,
+				query: request.query
+			}, request.maxResults);
+			return result;
+		} catch (error) {
+			if (signal?.aborted) throw new WebError("Web search aborted", "WEB_ABORTED");
+			failure = timeout.aborted ? new SearchProviderError(id, "TIMEOUT") : error instanceof SearchProviderError ? error : new SearchProviderError(id, "UNKNOWN");
+			throw failure;
+		} finally {
+			this.ctx.logger("web-search").info("provider=%s queries=1 duration=%d results=%d status=%s retries=0 error=%s", id, Date.now() - started, result?.sources.length ?? 0, result?.statusCode ?? failure?.statusCode ?? "-", failure?.code ?? "-");
+		}
+	}
+	/**
+	* 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.
+	* Configured fallbacks share the caller signal and retry only provider or
+	* credential unavailability; missing registrations and cancellation stop the chain.
+	* @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) {
+		if (this.requireSearchSelection) {
+			const settings = this.searchSettings();
+			if (!settings.enabled) throw new SearchProviderError(settings.provider, "CONFIG_ERROR", void 0, "Web Search is disabled in Settings > Web Search.");
+			if (settings.provider === "") throw new SearchProviderError("", "CONFIG_ERROR", void 0, "Web Search is enabled but no search provider has been configured. Open Settings > Web Search and select a provider.");
+			return this.runSearchProvider(settings.provider, request, signal);
+		}
+		if (this.searchFallbackProviders.length > 0) {
+			const providers = [this.searchProviderId, ...this.searchFallbackProviders].map((id) => {
+				const provider = this.searchProviders.get(id);
+				if (provider === void 0) throw new WebError(`configured web provider "${id}" is not registered`, "WEB_PROVIDER_CONFIGURED_MISSING");
+				return provider;
+			});
+			let failure;
+			for (const provider of providers) {
+				if (signal?.aborted) throw new WebError("web search aborted", "WEB_ABORTED", { cause: signal.reason });
+				try {
+					if (!provider.available()) throw new WebError(`configured web provider "${provider.id}" is unavailable`, "WEB_PROVIDER_CONFIGURED_UNAVAILABLE");
+					return capSources(await provider.search(request, signal), request.maxResults);
+				} catch (error) {
+					const retryable = error instanceof SearchProviderError ? error.retryable : error instanceof WebError && [
+						"WEB_PROVIDER_ERROR",
+						"WEB_PROVIDER_CREDENTIAL_MISSING",
+						"WEB_PROVIDER_CONFIGURED_UNAVAILABLE"
+					].includes(error.code);
+					if (signal?.aborted || !retryable) throw error;
+					failure = error;
+				}
+			}
+			throw failure;
+		}
+		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 { SearchProviderError, WEB_SEARCH_CAPABILITIES, WebError, WebRuntime, WebRuntime as default, normalizedSearchUrl, searchHttpError };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@hydraharness/harness-web`.
+* @module @hydraharness/harness-web/invariant
+*/
+const PACKAGE_NAME = "@hydraharness/harness-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,131 @@
+/**
+ * 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 @hydraharness/harness-web
+ */
+import { Context, Service } from '@hydraharness/cordis';
+import z from '@hydraharness/schemastery';
+import { type WebSearchSettings } from './settings.ts';
+import { type WebSearchProviderDescriptor } from './search.ts';
+import type { WebFetchProvider, WebFetchRequest, WebFetchResult, WebSearchProvider, WebSearchRequest, WebSearchResult } from './types.ts';
+export { WebError, } from './types.ts';
+export { normalizedSearchUrl, SearchProviderError, searchHttpError, WEB_SEARCH_CAPABILITIES } from './search.ts';
+export type { SearchConfigField, SearchErrorCode, WebSearchProviderDescriptor, WebSearchType } from './search.ts';
+export type { WebSearchSettings } from './settings.ts';
+export type { WebFetchBody, WebFetchProvider, WebFetchRequest, WebFetchResult, WebSearchProvider, WebSearchRequest, WebSearchResult, WebSearchSource, } from './types.ts';
+declare module '@hydraharness/cordis' {
+    interface Context {
+        web: WebRuntime;
+    }
+}
+/**
+ * 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 WebRuntimeConfig {
+    /** Product Settings owns selection; no single-provider auto-selection. */
+    readonly requireSearchSelection?: boolean;
+    /** 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;
+    /** Ordered backup search providers; requires an explicit primary searchProvider. Defaults to none. */
+    readonly searchFallbackProviders?: 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 WebRuntime extends Service {
+    /**
+     * Provider selection config. Operational env overrides feed the SAME fields:
+     * `$HYDRA_WEB_SEARCH_PROVIDER` / `$HYDRA_WEB_FETCH_PROVIDER` are equivalent to
+     * `searchProvider` / `fetchProvider` and are NOT a hidden priority chain.
+     */
+    static Config: z<WebRuntimeConfig>;
+    private searchProviders;
+    private fetchProviders;
+    private readonly searchProviderId;
+    private readonly fetchProviderId;
+    private readonly searchFallbackProviders;
+    private searchSettings;
+    private readonly requireSearchSelection;
+    constructor(ctx: Context, config?: WebRuntimeConfig);
+    /**
+     * Read current product limits; standalone compositions retain tool-level limits.
+     * @returns saved invocation preferences when product selection is enabled.
+     */
+    searchPreferences(): WebSearchSettings | undefined;
+    /**
+     * List provider-owned, secret-free Settings descriptors.
+     * @returns configurable providers in registration order.
+     */
+    listSearchProviders(): WebSearchProviderDescriptor[];
+    /**
+     * Persist the first search selection from explicit legacy configuration only.
+     * An explicit empty selection also marks a fresh installation as initialized.
+     * @param provider - legacy registered id.
+     * @param configured - whether a legacy search section contains explicit settings.
+     */
+    migrateSearchSelection(provider: string, configured: boolean): Promise<void>;
+    /**
+     * Execute a small real search with a saved provider without changing selection.
+     * @param id - registered provider to test.
+     * @param signal - caller cancellation.
+     * @returns normalized results after validating the provider response.
+     */
+    testSearchProvider(id: string, signal?: AbortSignal): Promise<WebSearchResult>;
+    private runSearchProvider;
+    /**
+     * 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.
+     * Configured fallbacks share the caller signal and retry only provider or
+     * credential unavailability; missing registrations and cancellation stop the chain.
+     * @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 WebRuntime;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@hydraharness/harness-web`.
+ * @module @hydraharness/harness-web/invariant
+ */
+import type { Context } from '@hydraharness/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/search.d.ts

@@ -0,0 +1,52 @@
+/** Shared search errors, provider configuration metadata, and URL normalization. */
+import { WebError } from './types.ts';
+/** Search types a provider may explicitly support. */
+export type WebSearchType = 'web' | 'images' | 'news' | 'videos' | 'academic';
+/** One provider-owned settings control; values live in its settings namespace. */
+export interface SearchConfigField {
+    key: string;
+    label: string;
+    kind: 'text' | 'number' | 'select' | 'json';
+    options?: string[];
+    advanced?: boolean;
+    hint?: string;
+}
+/** Secret-free provider metadata used by the Settings directory. */
+export interface WebSearchProviderDescriptor {
+    id: string;
+    displayName: string;
+    description?: string;
+    capabilities: Record<WebSearchType, boolean>;
+    configurable: boolean;
+    settingsNs: string;
+    credentialRef: string;
+    fields: SearchConfigField[];
+}
+/** Web-only capabilities; endpoints for other search types are not advertised. */
+export declare const WEB_SEARCH_CAPABILITIES: Record<WebSearchType, boolean>;
+/** Safe categories exposed to tools and configuration UIs. */
+export type SearchErrorCode = 'AUTH_ERROR' | 'RATE_LIMITED' | 'TIMEOUT' | 'NETWORK_ERROR' | 'INVALID_RESPONSE' | 'CONFIG_ERROR' | 'UNKNOWN';
+/** Search failure containing only owned diagnostics, never upstream text or causes. */
+export declare class SearchProviderError extends WebError {
+    readonly provider: string;
+    readonly code: SearchErrorCode;
+    readonly statusCode?: number | undefined;
+    /** Whether a later retry may succeed without reconfiguration. */
+    readonly retryable: boolean;
+    constructor(provider: string, code: SearchErrorCode, statusCode?: number | undefined, message?: string);
+}
+/**
+ * Translate an HTTP failure without reading an untrusted error body.
+ * @param provider - registered provider id.
+ * @param status - HTTP status.
+ * @returns the normalized failure.
+ */
+export declare function searchHttpError(provider: string, status: number): SearchProviderError;
+/**
+ * Remove fragments and common tracking parameters for duplicate detection.
+ * Non-root trailing slashes and meaningful query parameters remain distinct.
+ * @param value - source URL.
+ * @returns a canonical comparison key, or the unchanged malformed URL.
+ */
+export declare function normalizedSearchUrl(value: string): string;
+//# sourceMappingURL=search.d.ts.map

package/lib/types/settings.d.ts

@@ -0,0 +1,13 @@
+/** Product search selection and invocation limits, independent of chat configuration. */
+import z from '@hydraharness/schemastery';
+/** Saved search preferences. Empty provider requires an explicit user selection. */
+export interface WebSearchSettings {
+    enabled: boolean;
+    provider: string;
+    maxQueries: number;
+    maxResults: number;
+    timeoutMs: number;
+}
+/** Schema shared by registration and composition default resolution. */
+export declare const SearchSettings: z<Partial<WebSearchSettings>, WebSearchSettings>;
+//# sourceMappingURL=settings.d.ts.map

package/lib/types/types.d.ts

@@ -0,0 +1,139 @@
+/**
+ * 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 @hydraharness/harness-web/types
+ */
+import { HarnessError } from '@hydraharness/harness-llm';
+import type { WebSearchProviderDescriptor, WebSearchType } from './search.ts';
+/**
+ * What one search-capable backend is asked to search. Each request carries one
+ * query; a consumer may issue several requests. `maxResults` is a
+ * `@hydraharness/harness-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;
+    readonly type?: WebSearchType;
+    readonly country?: string;
+    readonly language?: string;
+    readonly date?: string;
+    /**
+     * Upper bound on returned sources; the seam truncates to it. Omitted = no
+     * bound. `@hydraharness/harness-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 shape. `truncated` is set by the seam
+ * when it cut `sources[]` down to `maxResults`.
+ */
+export interface WebSearchResult {
+    readonly provider?: string;
+    readonly query?: string;
+    readonly statusCode?: number;
+    /** 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). `@hydraharness/harness-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;
+    readonly provider?: string;
+    readonly position?: number;
+    readonly score?: number;
+}
+/**
+ * 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
+ * `@hydraharness/harness-web`: the provider decodes the kind and `@hydraharness/harness-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;
+    /** Configurable providers expose their own metadata; others stay out of Settings. */
+    readonly descriptor?: WebSearchProviderDescriptor;
+    /** 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,54 @@
+{
+  "name": "@hydraharness/harness-web",
+  "description": "Abstract web access capability seam (ctx.web) for the Hydra harness — search/fetch provider registry, registration-order-independent selection, request/result vocabulary, and the WebError taxonomy",
+  "hydra": {
+    "plugin": {
+      "application": "Route web searches and page fetches to the providers configured in the profile."
+    }
+  },
+  "version": "0.1.1-rc.10",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MaiHongPhong2010/Hydra-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": "MIT",
+  "peerDependencies": {
+    "@hydraharness/harness-invariants": "^0.1.1-rc.10",
+    "@hydraharness/harness-llm": "^0.1.1-rc.10",
+    "@hydraharness/cordis": "^4.0.2",
+    "@hydraharness/harness-settings": "^0.1.1-rc.10"
+  },
+  "dependencies": {
+    "@hydraharness/schemastery": "^3.18.2"
+  },
+  "devDependencies": {
+    "@hydraharness/harness-invariants": "^0.1.1-rc.10",
+    "@hydraharness/harness-llm": "^0.1.1-rc.10",
+    "@hydraharness/cordis": "^4.0.2",
+    "@hydraharness/harness-settings": "^0.1.1-rc.10"
+  }
+}