@xopcai/xopc 0.0.384 → 0.0.386

package/dist/src/agent/tools/search/errors.d.ts

@@ -0,0 +1,19 @@
+export type SearchFailureKind = 'permission_denied' | 'rate_limited' | 'timeout' | 'cancelled' | 'unsupported_batch' | 'provider_error';
+export interface SearchFailureInfo {
+    kind: SearchFailureKind;
+    scope: 'request' | 'batch' | 'provider';
+    message: string;
+    status?: number;
+    retryAfterMs?: number;
+}
+/** Only a host adapter may explicitly identify a refusal as batch-only. */
+export declare class SearchError extends Error implements SearchFailureInfo {
+    readonly kind: SearchFailureKind;
+    readonly scope: 'request' | 'batch' | 'provider';
+    readonly status?: number;
+    readonly retryAfterMs?: number;
+    constructor(info: SearchFailureInfo);
+}
+export declare function classifySearchError(error: unknown, signal?: AbortSignal): SearchError;
+export declare function searchFailureInfo(error: SearchError): SearchFailureInfo;
+export declare function searchHttpError(response: Response, message?: string): SearchError;

package/dist/src/agent/tools/search/errors.js

@@ -0,0 +1,69 @@
+//#region src/agent/tools/search/errors.ts
+/** Only a host adapter may explicitly identify a refusal as batch-only. */
+var SearchError = class extends Error {
+	kind;
+	scope;
+	status;
+	retryAfterMs;
+	constructor(info) {
+		super(info.message);
+		this.name = "SearchError";
+		this.kind = info.kind;
+		this.scope = info.scope;
+		this.status = info.status;
+		this.retryAfterMs = info.retryAfterMs;
+	}
+};
+function classifySearchError(error, signal) {
+	if (signal?.aborted) {
+		const reason = signal.reason;
+		const timedOut = reason?.name === "TimeoutError" || reason?.code === "deadline_exceeded";
+		return new SearchError({
+			kind: timedOut ? "timeout" : "cancelled",
+			scope: "request",
+			message: timedOut ? "Search caller deadline exceeded" : "Search cancelled by its caller"
+		});
+	}
+	if (error instanceof SearchError) return error;
+	const value = error;
+	const message = error instanceof Error ? error.message : String(error);
+	const legacyStatus = /^HTTP (\d{3})\b/.exec(message)?.[1];
+	const status = typeof value?.status === "number" ? value.status : typeof value?.statusCode === "number" ? value.statusCode : legacyStatus ? Number(legacyStatus) : void 0;
+	const denied = [
+		"EACCES",
+		"EPERM",
+		"PERMISSION_DENIED",
+		"permission_denied",
+		"ACCESS_DENIED"
+	].includes(String(value?.code)) || /\b(permission denied|access denied|forbidden|unauthorized|not authorized)\b/i.test(message);
+	const kind = status === 401 || status === 403 || denied ? "permission_denied" : status === 429 ? "rate_limited" : status === 408 || status === 504 || value?.name === "TimeoutError" || value?.code === "ETIMEDOUT" ? "timeout" : value?.name === "AbortError" ? "cancelled" : "provider_error";
+	return new SearchError({
+		kind,
+		scope: kind === "permission_denied" ? "provider" : "request",
+		status,
+		message: message.slice(0, 500)
+	});
+}
+function searchFailureInfo(error) {
+	return {
+		kind: error.kind,
+		scope: error.scope,
+		message: error.message.slice(0, 500),
+		status: error.status,
+		retryAfterMs: error.retryAfterMs
+	};
+}
+function searchHttpError(response, message = `Search request failed (${response.status})`) {
+	const retryAfter = response.headers.get("retry-after");
+	const seconds = retryAfter === null ? NaN : Number(retryAfter);
+	const retryAfterMs = retryAfter === null ? void 0 : Number.isFinite(seconds) ? Math.max(0, seconds * 1e3) : Math.max(0, Date.parse(retryAfter) - Date.now());
+	return new SearchError({
+		kind: response.status === 401 || response.status === 403 ? "permission_denied" : response.status === 429 ? "rate_limited" : response.status === 408 || response.status === 504 ? "timeout" : "provider_error",
+		scope: response.status === 401 || response.status === 403 ? "provider" : "request",
+		message: message.slice(0, 500),
+		status: response.status,
+		retryAfterMs: retryAfterMs !== void 0 && Number.isFinite(retryAfterMs) ? retryAfterMs : void 0
+	});
+}
+//#endregion
+export { SearchError, classifySearchError, searchFailureInfo, searchHttpError };

package/dist/src/agent/tools/search/providers/bing-api.js

@@ -1,3 +1,4 @@
+import { searchHttpError } from "../errors.js";
 //#region src/agent/tools/search/providers/bing-api.ts
 /** Azure Bing Web Search API (global endpoint; works without a proxy from many regions). */
 var BingApiProvider = class {
@@ -17,7 +18,7 @@ var BingApiProvider = class {
 			headers: { "Ocp-Apim-Subscription-Key": this.apiKey },
 			signal
 		});
-		if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
+		if (!response.ok) throw searchHttpError(response);
 		return ((await response.json()).webPages?.value ?? []).map((r) => ({
 			title: r.name ?? "",
 			url: r.url ?? "",

package/dist/src/agent/tools/search/providers/bing-html.js

@@ -1,3 +1,4 @@
+import { searchHttpError } from "../errors.js";
 import { DEFAULT_HTML_SEARCH_TIMEOUT_MS, HTML_SEARCH_USER_AGENT, mergeAbortWithTimeout } from "../http.js";
 //#region src/agent/tools/search/providers/bing-html.ts
 const BING_CN_SEARCH = "https://cn.bing.com/search";
@@ -22,7 +23,7 @@ var BingHtmlProvider = class {
 				"Accept-Language": "zh-CN,zh;q=0.9,en;q=0.8"
 			}
 		});
-		if (!response.ok) throw new Error(`HTTP ${response.status}`);
+		if (!response.ok) throw searchHttpError(response);
 		return parseBingCnHtml(await response.text(), count);
 	}
 };

package/dist/src/agent/tools/search/providers/brave.js

@@ -1,3 +1,4 @@
+import { searchHttpError } from "../errors.js";
 //#region src/agent/tools/search/providers/brave.ts
 var BraveProvider = class {
 	name = "brave";
@@ -17,7 +18,7 @@ var BraveProvider = class {
 			},
 			signal
 		});
-		if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
+		if (!response.ok) throw searchHttpError(response);
 		return ((await response.json()).web?.results ?? []).map((r) => ({
 			title: r.title ?? "",
 			url: r.url ?? "",

package/dist/src/agent/tools/search/providers/duckduckgo-html.js

@@ -1,3 +1,4 @@
+import { searchHttpError } from "../errors.js";
 import { DEFAULT_HTML_SEARCH_TIMEOUT_MS, HTML_SEARCH_USER_AGENT, mergeAbortWithTimeout } from "../http.js";
 //#region src/agent/tools/search/providers/duckduckgo-html.ts
 const DDG_HTML = "https://html.duckduckgo.com/html/";
@@ -23,7 +24,7 @@ var DuckDuckGoHtmlProvider = class {
 			},
 			body: body.toString()
 		});
-		if (!response.ok) throw new Error(`HTTP ${response.status}`);
+		if (!response.ok) throw searchHttpError(response);
 		return parseDdgHtml(await response.text(), count);
 	}
 };

package/dist/src/agent/tools/search/providers/searxng.js

@@ -1,3 +1,4 @@
+import { searchHttpError } from "../errors.js";
 //#region src/agent/tools/search/providers/searxng.ts
 var SearXNGProvider = class {
 	name = "searxng";
@@ -14,7 +15,7 @@ var SearXNGProvider = class {
 		url.searchParams.set("format", "json");
 		url.searchParams.set("categories", "general");
 		const response = await fetch(url, { signal });
-		if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
+		if (!response.ok) throw searchHttpError(response);
 		return ((await response.json()).results ?? []).slice(0, count).map((r) => ({
 			title: r.title ?? "",
 			url: r.url ?? "",

package/dist/src/agent/tools/search/providers/tavily.js

@@ -1,3 +1,4 @@
+import { searchHttpError } from "../errors.js";
 //#region src/agent/tools/search/providers/tavily.ts
 var TavilyProvider = class {
 	name = "tavily";
@@ -20,7 +21,7 @@ var TavilyProvider = class {
 			}),
 			signal
 		});
-		if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
+		if (!response.ok) throw searchHttpError(response);
 		return ((await response.json()).results ?? []).map((r) => ({
 			title: r.title ?? "",
 			url: r.url ?? "",

package/dist/src/agent/tools/search/providers/xopc-cloud.d.ts

@@ -14,6 +14,7 @@ export declare class XopcCloudSearchProvider implements SearchProvider {
     private readonly catalogStore;
     private readonly credentials;
     constructor(options: XopcCloudSearchProviderOptions);
+    cacheIdentity(): string;
     isAvailable(): boolean;
     search(query: string, count: number, signal?: AbortSignal): Promise<SearchResult[]>;
 }

package/dist/src/agent/tools/search/providers/xopc-cloud.js

@@ -1,5 +1,6 @@
 import { getModelCatalogStore, init_model_catalog_store } from "../../../../providers/model-catalog-store.js";
 import { getProviderAuthService, init_provider_auth_service } from "../../../../providers/provider-auth-service.js";
+import { searchHttpError } from "../errors.js";
 //#region src/agent/tools/search/providers/xopc-cloud.ts
 init_model_catalog_store();
 init_provider_auth_service();
@@ -14,6 +15,10 @@ var XopcCloudSearchProvider = class {
 		this.catalogStore = options.catalogStore ?? getModelCatalogStore();
 		this.credentials = options.credentials ?? getProviderAuthService();
 	}
+	cacheIdentity() {
+		const source = this.catalogStore.getSource("xopc-cloud");
+		return JSON.stringify([source?.baseUrl, source?.search]);
+	}
 	isAvailable() {
 		return Boolean(this.catalogStore.getSource("xopc-cloud")?.search);
 	}
@@ -22,7 +27,7 @@ var XopcCloudSearchProvider = class {
 		if (!source?.search) throw new Error("XOPC Cloud search is not available");
 		const requestSignal = signal ? AbortSignal.any([signal, AbortSignal.timeout(3e4)]) : AbortSignal.timeout(3e4);
 		const accessToken = await this.credentials.resolveApiKey("xopc-cloud", requestSignal);
-		if (!accessToken) throw new Error("XOPC Cloud is not connected");
+		if (!accessToken) throw searchHttpError(new Response(null, { status: 401 }), "XOPC Cloud is not connected");
 		const endpoint = `${source.baseUrl.replace(/\/+$/, "")}/${source.search.endpoint.replace(/^\/+/, "")}`;
 		const response = await this.fetchImpl(endpoint, {
 			method: "POST",
@@ -39,7 +44,7 @@ var XopcCloudSearchProvider = class {
 			signal: requestSignal
 		});
 		const body = await response.json().catch(() => null);
-		if (!response.ok) throw new Error(typeof body?.error?.message === "string" ? body.error.message : `XOPC Cloud search failed (${response.status})`);
+		if (!response.ok) throw searchHttpError(response, typeof body?.error?.message === "string" ? body.error.message : `XOPC Cloud search failed (${response.status})`);
 		if (!Array.isArray(body?.results)) throw new Error("XOPC Cloud search returned an invalid response");
 		return body.results.flatMap((result) => {
 			if (typeof result.title !== "string" || typeof result.url !== "string" || typeof result.description !== "string") return [];

package/dist/src/agent/tools/search/registry.d.ts

@@ -1,14 +1,30 @@
-import type { ResolvedWebSearchConfig, SearchProvider, SearchResult } from './types.js';
+import { type SearchCache } from './cache.js';
+import type { ResolvedWebSearchConfig, SearchProvider, SearchResponse, SearchRequest, SearchBatchResponse } from './types.js';
 export declare class SearchProviderRegistry {
     private readonly providers;
     private readonly fallbackProvider;
+    private readonly cache;
+    private readonly cachePrefix;
+    private readonly requestTimeoutMs;
+    private readonly retryDelayMs;
+    sourceRequests: number;
+    private readonly cooldowns;
     constructor(config: ResolvedWebSearchConfig, options?: {
         cloudProvider?: SearchProvider;
+        providers?: SearchProvider[];
+        fallbackProvider?: SearchProvider | null;
+        cache?: SearchCache;
+        requestTimeoutMs?: number;
+        retryDelayMs?: number;
     });
     private buildProviders;
     hasConfiguredApiProvider(): boolean;
-    search(query: string, count: number, signal?: AbortSignal): Promise<{
-        results: SearchResult[];
-        provider: string;
-    }>;
+    private key;
+    private cached;
+    private remember;
+    private attempt;
+    private backoff;
+    search(query: string, count: number, signal?: AbortSignal, authorize?: () => void): Promise<SearchResponse>;
+    /** Only unfinished, non-denied items degrade to sequential authorized searches. */
+    searchBatch(requests: SearchRequest[], signal?: AbortSignal, authorize?: () => void): Promise<SearchBatchResponse[]>;
 }

package/dist/src/agent/tools/search/registry.js

@@ -1,5 +1,8 @@
 import { createLogger } from "../../../utils/logger/index.js";
 import { init_logger } from "../../../utils/logger.js";
+import { executeWithTimeout } from "../../lifecycle/timeout-wrapper.js";
+import { SearchError, classifySearchError, searchFailureInfo } from "./errors.js";
+import { SearchCacheWriteError, currentSearchCache } from "./cache.js";
 import { BraveProvider } from "./providers/brave.js";
 import { TavilyProvider } from "./providers/tavily.js";
 import { BingApiProvider } from "./providers/bing-api.js";
@@ -7,15 +10,40 @@ import { BingHtmlProvider } from "./providers/bing-html.js";
 import { DuckDuckGoHtmlProvider } from "./providers/duckduckgo-html.js";
 import { SearXNGProvider } from "./providers/searxng.js";
 import { XopcCloudSearchProvider } from "./providers/xopc-cloud.js";
+import { createHash } from "node:crypto";
+import { setTimeout } from "node:timers/promises";
 //#region src/agent/tools/search/registry.ts
 init_logger();
 const log = createLogger("Agent:WebSearch");
 var SearchProviderRegistry = class {
 	providers;
 	fallbackProvider;
+	cache;
+	cachePrefix;
+	requestTimeoutMs;
+	retryDelayMs;
+	sourceRequests = 0;
+	cooldowns = /* @__PURE__ */ new Map();
 	constructor(config, options = {}) {
-		this.providers = this.buildProviders(config, options.cloudProvider);
-		this.fallbackProvider = config.region === "cn" ? new BingHtmlProvider() : new DuckDuckGoHtmlProvider();
+		this.providers = options.providers ?? this.buildProviders(config, options.cloudProvider);
+		this.fallbackProvider = options.fallbackProvider === void 0 ? config.region === "cn" ? new BingHtmlProvider() : new DuckDuckGoHtmlProvider() : options.fallbackProvider;
+		const cache = /* @__PURE__ */ new Map();
+		this.cache = options.cache ?? currentSearchCache() ?? {
+			get: (key) => cache.get(key),
+			set: (entry) => {
+				if (JSON.stringify(entry).length > 2e5) return;
+				cache.delete(entry.key);
+				cache.set(entry.key, entry);
+				while (cache.size > 20) cache.delete(cache.keys().next().value);
+			}
+		};
+		this.cachePrefix = createHash("sha256").update(JSON.stringify([
+			config,
+			this.providers.map((provider) => [provider.name, provider.cacheIdentity?.()]),
+			this.fallbackProvider?.name
+		])).digest("hex");
+		this.requestTimeoutMs = options.requestTimeoutMs ?? 1e4;
+		this.retryDelayMs = options.retryDelayMs ?? 300;
 		log.debug({
 			region: config.region,
 			configuredCount: this.providers.filter((p) => p.isAvailable()).length
@@ -50,33 +78,232 @@ var SearchProviderRegistry = class {
 	hasConfiguredApiProvider() {
 		return this.providers.some((p) => p.isAvailable());
 	}
-	async search(query, count, signal) {
-		for (const provider of this.providers) {
+	key(query, count) {
+		return createHash("sha256").update(JSON.stringify([
+			this.cachePrefix,
+			query.trim(),
+			count
+		])).digest("hex");
+	}
+	cached(query, count) {
+		const cached = this.cache.get(this.key(query, count));
+		return cached && Date.now() >= cached.capturedAt && Date.now() - cached.capturedAt < 6e5 ? {
+			results: structuredClone(cached.results),
+			provider: cached.provider,
+			cached: true,
+			capturedAt: cached.capturedAt
+		} : void 0;
+	}
+	remember(query, count, response) {
+		try {
+			this.cache.set({
+				key: this.key(query, count),
+				query: query.trim(),
+				count,
+				results: structuredClone(response.results),
+				provider: response.provider,
+				capturedAt: response.capturedAt ?? Date.now()
+			});
+		} catch (error) {
+			throw new SearchCacheWriteError(error);
+		}
+	}
+	async attempt(name, signal, execute) {
+		signal?.throwIfAborted();
+		this.sourceRequests++;
+		const controller = new AbortController();
+		const abort = () => controller.abort(signal?.reason);
+		signal?.addEventListener("abort", abort, { once: true });
+		try {
+			return await executeWithTimeout(() => execute(controller.signal), {
+				toolName: `web_search:${name}`,
+				timeoutMs: this.requestTimeoutMs,
+				signal,
+				onTimeout: (error) => controller.abort(error)
+			});
+		} catch (error) {
+			throw classifySearchError(error, signal);
+		} finally {
+			signal?.removeEventListener("abort", abort);
+		}
+	}
+	async backoff(error, signal) {
+		const waitMs = error.retryAfterMs ?? this.retryDelayMs;
+		if (waitMs > 2e3) return false;
+		await setTimeout(Math.max(0, waitMs), void 0, { signal });
+		return true;
+	}
+	async search(query, count, signal, authorize = () => {}) {
+		signal?.throwIfAborted();
+		authorize();
+		const hit = this.cached(query, count);
+		if (hit) return hit;
+		let lastError;
+		for (const provider of [...this.providers, ...this.fallbackProvider ? [this.fallbackProvider] : []]) {
+			signal?.throwIfAborted();
+			authorize();
 			if (!provider.isAvailable()) continue;
-			try {
-				return {
-					results: await provider.search(query, count, signal),
-					provider: provider.name
-				};
-			} catch (err) {
-				log.debug({
-					provider: provider.name,
-					err
-				}, "Search provider failed, trying next");
+			const cooldown = this.cooldowns.get(provider.name);
+			if (cooldown && cooldown.until > Date.now()) {
+				lastError = cooldown.error;
+				continue;
+			}
+			for (let attempt = 0; attempt < 2; attempt++) {
+				signal?.throwIfAborted();
+				authorize();
+				try {
+					const results = await this.attempt(provider.name, signal, (requestSignal) => provider.search(query, count, requestSignal));
+					signal?.throwIfAborted();
+					authorize();
+					const response = {
+						results,
+						provider: provider.name,
+						capturedAt: Date.now()
+					};
+					this.remember(query, count, response);
+					return response;
+				} catch (error) {
+					if (error instanceof SearchCacheWriteError) throw error;
+					const failure = classifySearchError(error, signal);
+					if (signal?.aborted || failure.kind === "permission_denied" || failure.kind === "cancelled") throw failure;
+					lastError = failure;
+					if (failure.kind === "rate_limited") this.cooldowns.set(provider.name, {
+						until: Date.now() + (failure.retryAfterMs ?? this.retryDelayMs),
+						error: failure
+					});
+					log.debug({
+						provider: provider.name,
+						kind: failure.kind,
+						attempt
+					}, "Search provider attempt failed");
+					if (attempt || !["rate_limited", "timeout"].includes(failure.kind) || !await this.backoff(failure, signal)) break;
+				}
 			}
 		}
-		try {
-			return {
-				results: await this.fallbackProvider.search(query, count, signal),
-				provider: this.fallbackProvider.name
-			};
-		} catch (err) {
-			log.warn({ err }, "HTML fallback search failed");
-			return {
-				results: [],
-				provider: "none"
-			};
+		throw lastError ?? new SearchError({
+			kind: "provider_error",
+			scope: "request",
+			message: "No search provider is available"
+		});
+	}
+	/** Only unfinished, non-denied items degrade to sequential authorized searches. */
+	async searchBatch(requests, signal, authorize = () => {}) {
+		if (!requests.length || requests.length > 8 || new Set(requests.map((request) => request.id)).size !== requests.length) throw new Error("Invalid search batch");
+		signal?.throwIfAborted();
+		authorize();
+		const outputs = /* @__PURE__ */ new Map();
+		const unique = /* @__PURE__ */ new Map();
+		for (const request of requests) {
+			const hit = this.cached(request.query, request.count);
+			if (hit) outputs.set(this.key(request.query, request.count), {
+				...request,
+				response: hit
+			});
+			else unique.set(this.key(request.query, request.count), request);
+		}
+		const pending = [...unique.values()];
+		const provider = this.providers.find((provider) => provider.isAvailable() && (this.cooldowns.get(provider.name)?.until ?? 0) <= Date.now());
+		const itemFailures = /* @__PURE__ */ new Map();
+		if (pending.length > 1 && provider?.searchBatch) try {
+			authorize();
+			const items = await this.attempt(provider.name, signal, (requestSignal) => provider.searchBatch(pending, requestSignal));
+			const ids = new Set(pending.map((request) => request.id));
+			if (items.some((item) => !ids.has(item.id)) || new Set(items.map((item) => item.id)).size !== items.length) throw new Error("Invalid batch search response ids");
+			signal?.throwIfAborted();
+			authorize();
+			let providerRefusal;
+			for (const request of pending) {
+				const item = items.find((item) => item.id === request.id);
+				if (item?.results && !item.error) {
+					const response = {
+						results: item.results,
+						provider: provider.name,
+						capturedAt: Date.now()
+					};
+					this.remember(request.query, request.count, response);
+					outputs.set(this.key(request.query, request.count), {
+						...request,
+						response
+					});
+				} else if (item?.error) {
+					if (item.error.kind === "permission_denied" && item.error.scope === "provider") providerRefusal = new SearchError(item.error);
+					if (["permission_denied", "cancelled"].includes(item.error.kind) && item.error.scope !== "batch") outputs.set(this.key(request.query, request.count), {
+						...request,
+						error: item.error
+					});
+					else {
+						const failure = new SearchError(item.error);
+						itemFailures.set(this.key(request.query, request.count), failure);
+						if (failure.kind === "rate_limited") this.cooldowns.set(provider.name, {
+							until: Date.now() + (failure.retryAfterMs ?? this.retryDelayMs),
+							error: failure
+						});
+					}
+				}
+			}
+			if (providerRefusal) for (const request of pending) {
+				const key = this.key(request.query, request.count);
+				if (!outputs.has(key)) outputs.set(key, {
+					...request,
+					error: searchFailureInfo(providerRefusal)
+				});
+			}
+		} catch (error) {
+			if (error instanceof SearchCacheWriteError) throw error;
+			const batchFailure = classifySearchError(error, signal);
+			if (signal?.aborted || batchFailure.kind === "permission_denied" && batchFailure.scope !== "batch" || batchFailure.kind === "cancelled") for (const request of pending) outputs.set(this.key(request.query, request.count), {
+				...request,
+				error: searchFailureInfo(batchFailure)
+			});
+			else if (batchFailure.kind === "rate_limited") {
+				this.cooldowns.set(provider.name, {
+					until: Date.now() + (batchFailure.retryAfterMs ?? this.retryDelayMs),
+					error: batchFailure
+				});
+				if (!await this.backoff(batchFailure, signal)) for (const request of pending) outputs.set(this.key(request.query, request.count), {
+					...request,
+					error: searchFailureInfo(batchFailure)
+				});
+			}
+		}
+		for (const request of pending) {
+			const key = this.key(request.query, request.count);
+			if (outputs.has(key)) continue;
+			try {
+				const itemFailure = itemFailures.get(key);
+				if (itemFailure?.kind === "rate_limited" && !await this.backoff(itemFailure, signal)) {
+					outputs.set(key, {
+						...request,
+						error: searchFailureInfo(itemFailure)
+					});
+					continue;
+				}
+				const response = await this.search(request.query, request.count, signal, authorize);
+				outputs.set(key, {
+					...request,
+					response,
+					...provider?.searchBatch ? { fallback: "individual" } : {}
+				});
+			} catch (error) {
+				const failure = classifySearchError(error, signal);
+				outputs.set(key, {
+					...request,
+					error: searchFailureInfo(failure),
+					...provider?.searchBatch ? { fallback: "individual" } : {}
+				});
+				if (failure.kind === "permission_denied" && failure.scope === "provider") for (const remaining of pending) {
+					const remainingKey = this.key(remaining.query, remaining.count);
+					if (!outputs.has(remainingKey)) outputs.set(remainingKey, {
+						...remaining,
+						error: searchFailureInfo(failure)
+					});
+				}
+			}
 		}
+		return requests.map((request) => ({
+			...outputs.get(this.key(request.query, request.count)),
+			...request
+		}));
 	}
 };
 //#endregion

package/dist/src/agent/tools/search/types.d.ts

@@ -1,3 +1,4 @@
+import type { SearchFailureInfo } from './errors.js';
 export interface SearchResult {
     title: string;
     url: string;
@@ -8,7 +9,10 @@ export interface SearchResult {
 export interface SearchProvider {
     name: string;
     isAvailable(): boolean;
+    cacheIdentity?(): string;
     search(query: string, count: number, signal?: AbortSignal): Promise<SearchResult[]>;
+    /** Optional host-implemented batch transport; ids must be echoed for partial results. */
+    searchBatch?(requests: SearchRequest[], signal?: AbortSignal): Promise<SearchBatchItem[]>;
 }
 export interface ResolvedSearchProviderEntry {
     type: 'brave' | 'tavily' | 'bing' | 'searxng';
@@ -22,3 +26,24 @@ export interface ResolvedWebSearchConfig {
     maxResults: number;
     providers: ResolvedSearchProviderEntry[];
 }
+export interface SearchRequest {
+    id: string;
+    query: string;
+    count: number;
+}
+export interface SearchBatchItem {
+    id: string;
+    results?: SearchResult[];
+    error?: SearchFailureInfo;
+}
+export interface SearchResponse {
+    results: SearchResult[];
+    provider: string;
+    cached?: boolean;
+    capturedAt?: number;
+}
+export interface SearchBatchResponse extends SearchRequest {
+    response?: SearchResponse;
+    error?: SearchFailureInfo;
+    fallback?: 'individual';
+}

package/dist/src/agent/tools/task-collaboration-tool.d.ts

@@ -0,0 +1,16 @@
+import type { AgentTool } from '@earendil-works/pi-agent-core';
+import { type XopcUseToolDeps } from './xopc-use-tool.js';
+declare const Schema: import("@sinclair/typebox").TObject<{
+    command: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"get">, import("@sinclair/typebox").TLiteral<"post">]>;
+    section: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"collaboration">, import("@sinclair/typebox").TLiteral<"task">]>>;
+    kind: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"progress">, import("@sinclair/typebox").TLiteral<"question">, import("@sinclair/typebox").TLiteral<"ack">]>>;
+    body: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    causationId: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    entryId: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    afterSequence: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+    limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+    idempotencyKey: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>;
+/** Collaboration only: no product mutations, connection selection or external operations. */
+export declare function createTaskCollaborationTool(deps: XopcUseToolDeps): AgentTool<typeof Schema>;
+export {};