@hydraharness/harness-web-search-http 0.1.1-rc.6

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,33 @@
+# @hydraharness/harness-web-search-http
+
+Serper and Other JSON HTTP search providers for [`ctx.web`](../web/README.md). They share transport and mapping mechanics but retain separate configuration and credentials. Mounting the plugin performs no network calls.
+
+## Configuration
+
+`web-search-serper` owns the result limit (8), request bounds, and the `SERPER_API_KEY` credential reference. Requests use POST `https://google.serper.dev/search`, `X-API-KEY`, and `{q,num}` plus `gl`/`hl` only when the agent supplies country/language hints. Hydra applies no saved locale defaults. Organic title/link/snippet/position fields become normalized sources.
+
+`web-search-custom` owns the endpoint, display name, GET/POST method, authentication, request fields, and response paths. Empty endpoint is unconfigured. Authentication supports none, Bearer, API key header, and custom header; all values resolve through the existing credential service, defaulting to `CUSTOM_SEARCH_API_KEY`. GET encodes fields as query parameters; POST sends JSON. Nested GET values are JSON strings.
+
+Request mapping includes query and limit plus optional country, language, type, and date fields. Response mapping includes results, title, URL, snippet, published date, score, and position. Dot paths permit simple identifiers and reject prototype traversal and expressions. The results path must name an array; each result needs an HTTP(S) URL. Incorrect configured mappings fail the connection test and search as `INVALID_RESPONSE`.
+
+Advanced `headerRefs` JSON maps header names to credential references, never literals. `staticBody` accepts non-secret JSON fields; credential-like names are rejected. Endpoints cannot contain userinfo or credential-like query parameters. Redirects are refused before forwarding credentials. Responses are limited to `maxResponseBytes` (5,000,000 by default) before JSON parsing. Provider timeouts default to 60000 ms and combine with caller cancellation. Keys are resolved for every operation and never retained on the provider. Responses echoing a resolved credential are rejected before returning sources.
+
+## Model Experience
+
+### Conversation search results
+
+#### What the model sees
+
+The [`tool-web`](../tool-web/README.md) consumer emits bounded normalized sources or shared safe errors. Registration adds no model input; Serper and Other do not invoke a language model.
+
+#### Token effect
+
+Result tokens scale with retained source text. Credentials and raw provider responses are excluded.
+
+#### KV Cache effect
+
+Only appended tool results affect subsequent context; switching the provider does not alter the tool argument schema.
+
+## Known Limitations and Deferred Work
+
+- Only web search is implemented. There is no automatic fallback, aggregation across providers, or reranking. Operators choose custom endpoints; private search services are permitted because the endpoint is configuration, not model input. Non-root trailing-slash equivalence is not assumed. Arbitrary expressions and secret literals in static request configuration are unsupported.

package/lib/index.js

@@ -0,0 +1,433 @@
+import z from "@hydraharness/schemastery";
+import { credentialRef } from "@hydraharness/harness-credentials";
+import { launchEnvironmentOf } from "@hydraharness/harness-launch-environment";
+import { installSettingsSection, settingsNamespace } from "@hydraharness/harness-settings";
+import { SearchProviderError, WEB_SEARCH_CAPABILITIES, WebError, searchHttpError } from "@hydraharness/harness-web";
+//#region lib/types/provider.js
+/** Bounded JSON HTTP requests and simple dot-path mapping for search providers. */
+const forbidden = /^(?:__proto__|prototype|constructor)$/;
+const secretName = /authorization|cookie|password|secret|token|api[-_]?key/i;
+/** Accept only own-property paths; no indexing, expressions, or prototype traversal. */
+function pathParts(path) {
+	const parts = path.split(".");
+	if (!parts.every((part) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(part) && !forbidden.test(part))) throw new Error("Search mapping paths must contain simple dot-separated field names.");
+	return parts;
+}
+/** Parse user JSON without allowing credential-like fields or prototype mutation. */
+function objectJson(text, headers = false) {
+	let value;
+	try {
+		value = JSON.parse(text);
+	} catch {
+		throw new Error("Search JSON must be a valid object.");
+	}
+	if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error("Search JSON must be an object.");
+	const visit = (item) => {
+		if (item === null || typeof item !== "object") return;
+		for (const [key, child] of Object.entries(item)) {
+			if (forbidden.test(key) || !headers && secretName.test(key)) throw new Error("Store search credentials through the credential controls, not request JSON.");
+			visit(child);
+		}
+	};
+	visit(value);
+	return value;
+}
+/**
+* Reject unsafe paths, credential-bearing endpoints, and malformed JSON at save/load.
+* An empty endpoint is a valid unconfigured draft, rejected at execution.
+* @param config - resolved provider configuration.
+*/
+function validateSearchConfig(config) {
+	credentialRef(config.apiKeyEnv);
+	if (config.endpoint !== "") {
+		let url;
+		try {
+			url = new URL(config.endpoint);
+		} catch {
+			throw new Error("Search endpoint must be an HTTP(S) URL.");
+		}
+		if (!["http:", "https:"].includes(url.protocol) || url.username || url.password || url.hash || [...url.searchParams.keys()].some((key) => secretName.test(key))) throw new Error("Search endpoint must be HTTP(S) without embedded credentials or a fragment.");
+	}
+	for (const path of [
+		config.queryField,
+		config.resultsPath,
+		config.urlField
+	]) pathParts(path);
+	for (const path of [
+		config.limitField,
+		config.titleField,
+		config.snippetField,
+		config.publishedAtField,
+		config.scoreField,
+		config.positionField,
+		config.countryField,
+		config.languageField,
+		config.typeField,
+		config.dateField
+	]) if (path !== "") pathParts(path);
+	if (config.auth !== "none" && config.auth !== "bearer") new Headers({ [config.authHeader]: "validation" });
+	for (const [key, ref] of Object.entries(objectJson(config.headerRefs, true))) {
+		new Headers({ [key]: "validation" });
+		if (/^(host|content-length|transfer-encoding|connection)$/i.test(key)) throw new Error("Search transport headers cannot be overridden.");
+		if (typeof ref !== "string") throw new Error("Custom header values must be credential references.");
+		credentialRef(ref);
+	}
+	objectJson(config.staticBody);
+}
+/** Read only own properties from untrusted JSON. */
+function at(value, path) {
+	if (path === "") return void 0;
+	for (const part of pathParts(path)) {
+		if (value === null || typeof value !== "object" || !Object.hasOwn(value, part)) return void 0;
+		value = value[part];
+	}
+	return value;
+}
+/** Assign one validated dot-path without mutating static input objects. */
+function put(target, path, value) {
+	if (path === "" || value === void 0) return;
+	const parts = pathParts(path);
+	for (const part of parts.slice(0, -1)) {
+		const child = target[part];
+		if (child === null || typeof child !== "object" || Array.isArray(child)) target[part] = {};
+		target = target[part];
+	}
+	target[parts.at(-1)] = value;
+}
+/** Shared provider mechanics; provider routing remains in ctx.web. */
+var HttpSearchProvider = class {
+	descriptor;
+	current;
+	resolveKey;
+	id;
+	constructor(descriptor, current, resolveKey) {
+		this.descriptor = descriptor;
+		this.current = current;
+		this.resolveKey = resolveKey;
+		this.id = descriptor.id;
+	}
+	available() {
+		return this.current().endpoint !== "";
+	}
+	async search(request, signal) {
+		const config = this.current();
+		const timeout = AbortSignal.timeout(config.timeoutMs);
+		const bounded = signal === void 0 ? timeout : AbortSignal.any([signal, timeout]);
+		let status;
+		const keys = [];
+		try {
+			validateSearchConfig(config);
+			if (config.endpoint === "" || request.type !== void 0 && request.type !== "web") throw new SearchProviderError(this.id, "CONFIG_ERROR");
+			const headers = new Headers({
+				"Content-Type": "application/json",
+				Accept: "application/json"
+			});
+			const keyFor = async (ref) => {
+				bounded.throwIfAborted();
+				const cancelled = Promise.withResolvers();
+				const onAbort = () => {
+					cancelled.reject(new SearchProviderError(this.id, "TIMEOUT"));
+				};
+				bounded.addEventListener("abort", onAbort, { once: true });
+				let key;
+				try {
+					key = await Promise.race([this.resolveKey(ref), cancelled.promise]);
+				} catch {
+					throw new SearchProviderError(this.id, "CONFIG_ERROR");
+				} finally {
+					bounded.removeEventListener("abort", onAbort);
+				}
+				if (!key) throw new SearchProviderError(this.id, "CONFIG_ERROR");
+				keys.push(key);
+				return key;
+			};
+			for (const [header, ref] of Object.entries(objectJson(config.headerRefs, true))) headers.set(header, await keyFor(ref));
+			if (config.auth !== "none") {
+				const key = await keyFor(config.apiKeyEnv);
+				headers.set(config.auth === "bearer" ? "Authorization" : config.authHeader, config.auth === "bearer" ? `Bearer ${key}` : key);
+			}
+			const body = objectJson(config.staticBody);
+			put(body, config.queryField, request.query);
+			put(body, config.limitField, Math.min(request.maxResults ?? config.maxResults, config.maxResults));
+			put(body, config.countryField, request.country);
+			put(body, config.languageField, request.language);
+			put(body, config.typeField, request.type ?? "web");
+			put(body, config.dateField, request.date);
+			const endpoint = new URL(config.endpoint);
+			if (config.method === "GET") for (const [key, value] of Object.entries(body)) endpoint.searchParams.set(key, typeof value === "string" ? value : JSON.stringify(value));
+			const response = await fetch(endpoint, {
+				method: config.method,
+				headers,
+				redirect: "error",
+				signal: bounded,
+				...config.method === "POST" ? { body: JSON.stringify(body) } : {}
+			});
+			status = response.status;
+			if (!response.ok) {
+				await response.body?.cancel();
+				throw searchHttpError(this.id, status);
+			}
+			let payload;
+			let bytes = 0;
+			const bodyStream = response.body?.pipeThrough(new TransformStream({ transform: (chunk, controller) => {
+				bytes += chunk.byteLength;
+				if (bytes > config.maxResponseBytes) throw new SearchProviderError(this.id, "INVALID_RESPONSE", status);
+				controller.enqueue(chunk);
+			} }));
+			try {
+				payload = await new Response(bodyStream).json();
+			} catch {
+				throw new SearchProviderError(this.id, "INVALID_RESPONSE", status);
+			}
+			const items = at(payload, config.resultsPath);
+			if (!Array.isArray(items)) throw new SearchProviderError(this.id, "INVALID_RESPONSE", status);
+			const sources = items.map((item) => {
+				const url = at(item, config.urlField);
+				if (typeof url !== "string" || !URL.canParse(url) || !["http:", "https:"].includes(new URL(url).protocol)) throw new SearchProviderError(this.id, "INVALID_RESPONSE", status);
+				const source = { url };
+				for (const [key, path] of [
+					["title", config.titleField],
+					["snippet", config.snippetField],
+					["publishedAt", config.publishedAtField]
+				]) {
+					const value = at(item, path);
+					if (value !== void 0 && value !== null && typeof value !== "string") throw new SearchProviderError(this.id, "INVALID_RESPONSE", status);
+					if (typeof value === "string") source[key] = value;
+				}
+				for (const [key, path] of [["score", config.scoreField], ["position", config.positionField]]) {
+					const value = at(item, path);
+					if (value !== void 0 && (typeof value !== "number" || !Number.isFinite(value))) throw new SearchProviderError(this.id, "INVALID_RESPONSE", status);
+					if (typeof value === "number") source[key] = value;
+				}
+				return source;
+			});
+			if (keys.some((key) => JSON.stringify(sources).includes(key))) throw new SearchProviderError(this.id, "INVALID_RESPONSE", status);
+			return {
+				sources,
+				truncated: false,
+				statusCode: status
+			};
+		} catch (error) {
+			if (timeout.aborted || signal?.aborted && signal.reason instanceof DOMException && signal.reason.name === "TimeoutError") throw new SearchProviderError(this.id, "TIMEOUT", status);
+			if (signal?.aborted) throw new WebError("Web search aborted", "WEB_ABORTED");
+			if (error instanceof SearchProviderError) throw error;
+			throw new SearchProviderError(this.id, "NETWORK_ERROR", status);
+		}
+	}
+};
+//#endregion
+//#region lib/types/index.js
+/** Serper and configurable JSON search providers registered on the existing web service. */
+/** Cordis plugin name. */
+const name = "web-search-http";
+/** Search registry required by both provider registrations. */
+const inject = ["web"];
+const fields = [
+	{
+		key: "displayName",
+		label: "Provider Name",
+		kind: "text"
+	},
+	{
+		key: "endpoint",
+		label: "Endpoint",
+		kind: "text"
+	},
+	{
+		key: "method",
+		label: "HTTP Method",
+		kind: "select",
+		options: ["POST", "GET"]
+	},
+	{
+		key: "auth",
+		label: "Authentication",
+		kind: "select",
+		options: [
+			"none",
+			"bearer",
+			"api_key_header",
+			"custom_header"
+		]
+	},
+	{
+		key: "authHeader",
+		label: "API Key / Custom Header Name",
+		kind: "text"
+	},
+	{
+		key: "queryField",
+		label: "Query Field",
+		kind: "text"
+	},
+	{
+		key: "limitField",
+		label: "Limit Field",
+		kind: "text"
+	},
+	{
+		key: "resultsPath",
+		label: "Results Path",
+		kind: "text"
+	},
+	{
+		key: "titleField",
+		label: "Title Field",
+		kind: "text"
+	},
+	{
+		key: "urlField",
+		label: "URL Field",
+		kind: "text"
+	},
+	{
+		key: "snippetField",
+		label: "Snippet Field",
+		kind: "text"
+	},
+	{
+		key: "maxResults",
+		label: "Provider Result Limit",
+		kind: "number"
+	},
+	{
+		key: "timeoutMs",
+		label: "Provider Timeout (ms)",
+		kind: "number",
+		advanced: true
+	},
+	{
+		key: "maxResponseBytes",
+		label: "Maximum Response Bytes",
+		kind: "number",
+		advanced: true
+	},
+	{
+		key: "headerRefs",
+		label: "Custom Headers",
+		kind: "json",
+		advanced: true,
+		hint: "JSON mapping header names to credential references; store values through Credentials."
+	},
+	{
+		key: "staticBody",
+		label: "Static Request JSON",
+		kind: "json",
+		advanced: true,
+		hint: "Non-secret request fields only."
+	},
+	...[
+		["countryField", "Country Field"],
+		["languageField", "Language Field"],
+		["typeField", "Search Type Field"],
+		["dateField", "Date Field"],
+		["publishedAtField", "Published Date Mapping"],
+		["scoreField", "Score Mapping"],
+		["apiKeyEnv", "Credential Reference"]
+	].map(([key, label]) => ({
+		key,
+		label,
+		kind: "text",
+		advanced: true
+	}))
+];
+/** Custom provider settings contain credential references and non-secret mapping values. */
+const CustomConfig = z.object({
+	displayName: z.string().default("My Search Provider"),
+	endpoint: z.string().default(""),
+	method: z.union(["POST", "GET"]).default("POST"),
+	auth: z.union([
+		"none",
+		"bearer",
+		"api_key_header",
+		"custom_header"
+	]).default("api_key_header"),
+	authHeader: z.string().default("X-API-KEY"),
+	apiKeyEnv: z.string().role("credential-ref").default("CUSTOM_SEARCH_API_KEY"),
+	queryField: z.string().default("q"),
+	limitField: z.string().default("num"),
+	resultsPath: z.string().default("results"),
+	titleField: z.string().default("title"),
+	urlField: z.string().default("url"),
+	snippetField: z.string().default("snippet"),
+	publishedAtField: z.string().default(""),
+	scoreField: z.string().default(""),
+	positionField: z.string().default(""),
+	countryField: z.string().default(""),
+	languageField: z.string().default(""),
+	typeField: z.string().default(""),
+	dateField: z.string().default(""),
+	headerRefs: z.string().default("{}"),
+	staticBody: z.string().default("{}"),
+	timeoutMs: z.number().step(1).min(1).max(6e5).default(6e4),
+	maxResponseBytes: z.number().step(1).min(1).default(5e6),
+	maxResults: z.number().step(1).min(1).max(100).default(8)
+});
+/** Both provider configurations are validated before registration. */
+const Config = z.object({
+	serper: z.object({
+		apiKeyEnv: z.string().role("credential-ref").default("SERPER_API_KEY"),
+		maxResults: z.number().step(1).min(1).max(100).default(8),
+		timeoutMs: z.number().step(1).min(1).max(6e5).default(6e4),
+		maxResponseBytes: z.number().step(1).min(1).default(5e6)
+	}),
+	custom: CustomConfig
+});
+/**
+* Mount both HTTP adapters, with independently hot-reloaded settings and credentials.
+* @param ctx - search, settings, and credential services.
+* @param config - optional deployment overrides.
+*/
+function apply(ctx, config) {
+	register(ctx, "serper", "Serper.dev", CustomConfig({
+		...config.serper,
+		endpoint: "https://google.serper.dev/search",
+		method: "POST",
+		auth: "api_key_header",
+		authHeader: "X-API-KEY",
+		apiKeyEnv: config.serper?.apiKeyEnv ?? "SERPER_API_KEY",
+		resultsPath: "organic",
+		titleField: "title",
+		urlField: "link",
+		snippetField: "snippet",
+		positionField: "position",
+		queryField: "q",
+		limitField: "num",
+		countryField: "gl",
+		languageField: "hl"
+	}), fields.filter((field) => [
+		"maxResults",
+		"apiKeyEnv",
+		"timeoutMs",
+		"maxResponseBytes"
+	].includes(field.key)));
+	register(ctx, "custom", "Other", CustomConfig(config.custom ?? {}), fields);
+}
+/** Register one adapter and its saved configuration without retaining resolved keys. */
+function register(ctx, id, displayName, base, controls) {
+	validateSearchConfig(base);
+	let current = () => base;
+	const descriptor = {
+		id,
+		displayName,
+		configurable: true,
+		capabilities: WEB_SEARCH_CAPABILITIES,
+		settingsNs: `web-search-${id}`,
+		credentialRef: base.apiKeyEnv,
+		fields: controls
+	};
+	installSettingsSection(ctx, settingsNamespace(descriptor.settingsNs), CustomConfig, base, {
+		setSource: (source) => {
+			current = source;
+		},
+		onChange: () => {},
+		validate: validateSearchConfig
+	});
+	ctx.web.registerSearchProvider(new HttpSearchProvider(descriptor, () => current(), async (ref) => {
+		const credentials = ctx.get("credentials");
+		if (credentials !== void 0) return (await credentials.resolve(credentialRef(ref)))?.value;
+		return launchEnvironmentOf(ctx).get(ref)?.value;
+	}));
+}
+//#endregion
+export { Config, CustomConfig, HttpSearchProvider, apply, inject, name, validateSearchConfig };

package/lib/invariant.js

@@ -0,0 +1,22 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@hydraharness/harness-web-search-http`.
+* @module @hydraharness/harness-web-search-http/invariant
+*/
+const PACKAGE_NAME = "@hydraharness/harness-web-search-http";
+/** Cordis companion plugin name. */
+const name = "web-search-http-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: request mapping has no independent mutable state; provider registration ownership is checked by the web service.
+*/
+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,28 @@
+/** Serper and configurable JSON search providers registered on the existing web service. */
+import type { Context } from '@hydraharness/cordis';
+import z from '@hydraharness/schemastery';
+import type { HttpSearchConfig } from './provider.ts';
+export { HttpSearchProvider, validateSearchConfig } from './provider.ts';
+export type { HttpSearchConfig } from './provider.ts';
+/** Cordis plugin name. */
+export declare const name = "web-search-http";
+/** Search registry required by both provider registrations. */
+export declare const inject: string[];
+/** Custom provider settings contain credential references and non-secret mapping values. */
+export declare const CustomConfig: z<Partial<HttpSearchConfig>, HttpSearchConfig>;
+/** Operator bases for the independent saved provider sections. */
+export interface Config {
+    /** Serper credential reference and request limits. */
+    serper?: Pick<Partial<HttpSearchConfig>, 'apiKeyEnv' | 'maxResults' | 'timeoutMs' | 'maxResponseBytes'>;
+    /** Other provider endpoint, authentication, and JSON mappings. */
+    custom?: Partial<HttpSearchConfig>;
+}
+/** Both provider configurations are validated before registration. */
+export declare const Config: z<Config>;
+/**
+ * Mount both HTTP adapters, with independently hot-reloaded settings and credentials.
+ * @param ctx - search, settings, and credential services.
+ * @param config - optional deployment overrides.
+ */
+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 `@hydraharness/harness-web-search-http`.
+ * @module @hydraharness/harness-web-search-http/invariant
+ */
+import type { Context } from '@hydraharness/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "web-search-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/provider.d.ts

@@ -0,0 +1,70 @@
+/** Bounded JSON HTTP requests and simple dot-path mapping for search providers. */
+import type { WebSearchProvider, WebSearchProviderDescriptor, WebSearchRequest, WebSearchResult } from '@hydraharness/harness-web';
+/** Fully resolved, secret-free configuration captured once per request. */
+export interface HttpSearchConfig {
+    /** Name shown for this configured search service. */
+    displayName: string;
+    /** HTTP(S) search URL; empty means unconfigured. */
+    endpoint: string;
+    /** Query parameters for GET, JSON body for POST. */
+    method: 'GET' | 'POST';
+    /** Authentication scheme for the primary credential. */
+    auth: 'none' | 'bearer' | 'api_key_header' | 'custom_header';
+    /** Header receiving the primary key for header authentication. */
+    authHeader: string;
+    /** Credential reference; never a plaintext key. */
+    apiKeyEnv: string;
+    /** Dot-path receiving the search query. */
+    queryField: string;
+    /** Dot-path receiving the provider result cap; empty omits it. */
+    limitField: string;
+    /** Dot-path to the response result array. */
+    resultsPath: string;
+    /** Result title dot-path; empty omits it. */
+    titleField: string;
+    /** Result URL dot-path; must resolve to an HTTP(S) URL. */
+    urlField: string;
+    /** Result excerpt dot-path; empty omits it. */
+    snippetField: string;
+    /** Publication date dot-path; empty omits it. */
+    publishedAtField: string;
+    /** Numeric relevance score dot-path; empty omits it. */
+    scoreField: string;
+    /** Numeric provider rank dot-path; empty omits it. */
+    positionField: string;
+    /** Country request dot-path; empty omits it. */
+    countryField: string;
+    /** Language request dot-path; empty omits it. */
+    languageField: string;
+    /** Search type request dot-path; empty omits it. */
+    typeField: string;
+    /** Date filter request dot-path; empty omits it. */
+    dateField: string;
+    /** JSON object mapping custom header names to credential references. */
+    headerRefs: string;
+    /** JSON object with non-secret constant request fields. */
+    staticBody: string;
+    /** Whole-request deadline in milliseconds, including credentials. */
+    timeoutMs: number;
+    /** Maximum JSON response size in bytes before parsing. */
+    maxResponseBytes: number;
+    /** Provider request limit; the common tool may impose a smaller total. */
+    maxResults: number;
+}
+/**
+ * Reject unsafe paths, credential-bearing endpoints, and malformed JSON at save/load.
+ * An empty endpoint is a valid unconfigured draft, rejected at execution.
+ * @param config - resolved provider configuration.
+ */
+export declare function validateSearchConfig(config: HttpSearchConfig): void;
+/** Shared provider mechanics; provider routing remains in ctx.web. */
+export declare class HttpSearchProvider implements WebSearchProvider {
+    readonly descriptor: WebSearchProviderDescriptor;
+    private readonly current;
+    private readonly resolveKey;
+    readonly id: string;
+    constructor(descriptor: WebSearchProviderDescriptor, current: () => HttpSearchConfig, resolveKey: (ref: string) => Promise<string | undefined>);
+    available(): boolean;
+    search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult>;
+}
+//# sourceMappingURL=provider.d.ts.map

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@hydraharness/harness-web-search-http",
+  "description": "Serper and configurable JSON HTTP search providers",
+  "hydra": {
+    "plugin": {
+      "application": "Search through Serper or a configured JSON HTTP search endpoint."
+    }
+  },
+  "version": "0.1.1-rc.6",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MaiHongPhong1902/Hydra-Harness.git",
+    "directory": "packages/web/web-search-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": {
+    "@hydraharness/harness-credentials": "^0.1.1-rc.6",
+    "@hydraharness/harness-launch-environment": "^0.1.1-rc.6",
+    "@hydraharness/harness-web": "^0.1.1-rc.6",
+    "@hydraharness/harness-settings": "^0.1.1-rc.6",
+    "@hydraharness/cordis": "^4.0.2",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.6"
+  },
+  "dependencies": {
+    "@hydraharness/schemastery": "^3.18.2"
+  },
+  "devDependencies": {
+    "@hydraharness/harness-launch-environment": "^0.1.1-rc.6",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.6",
+    "@hydraharness/harness-web": "^0.1.1-rc.6",
+    "@hydraharness/harness-credentials": "^0.1.1-rc.6",
+    "@hydraharness/cordis": "^4.0.2",
+    "@hydraharness/harness-web-search-deepseek": "^0.1.1-rc.6",
+    "@hydraharness/harness-settings": "^0.1.1-rc.6"
+  }
+}