@nijaru/pi-search 0.0.7 → 0.0.9

package/src/fetcher.ts

@@ -1,5 +1,7 @@
 import { Worker } from "node:worker_threads";
-import type { FetchRequest, FetchedContent, FetchOutputFormat } from "./contracts";
+import type { FetchRequest, FetchedContent, FetchOutputFormat, FetchExtraction, FetchWarning, XReadMode } from "./contracts";
+import { parseXUrl, readFxTwitter, type XUrl } from "./x-public";
+import type { XBrowserReader, XBrowserSelection } from "./x-browser";
 import { SafeFetchError } from "./fetch-errors";
 import { closeResponseBody, fetchRemoteUrl, type Lookup, type ResponseBody } from "./ssrf";
 import type { DirectTransport } from "./direct-transport";
@@ -27,12 +29,13 @@ const MAX_OUTPUT_BYTES = 32_000;
 
 type NormalizedFetchRequest = Required<Pick<FetchRequest, "url" | "maxLength" | "offset" | "format" | "readable" | "allowRawHtmlFallback" | "captionLanguage">> & {
 	readonly maxPages: number | undefined;
+	readonly xMode: XReadMode | undefined;
 };
 
 interface ExtractedContent {
 	readonly content: string;
 	readonly outputFormat: FetchOutputFormat;
-	readonly extraction: "readability" | "raw" | "plain-text" | "markdown" | "document" | "pdf" | "youtube-transcript";
+	readonly extraction: FetchExtraction;
 	readonly documentFormat?: string;
 	readonly title?: string;
 	readonly fellBackToRaw?: boolean;
@@ -49,6 +52,8 @@ export interface FetcherOptions {
 	readonly pdfMaxOutputBytes?: number;
 	readonly youtubeMaxOutputBytes?: number;
 	readonly documentConverter?: DocumentConverter;
+	/** Explicitly owned, user-authorized browser access. Never global auth discovery. */
+	readonly xBrowser?: XBrowserReader;
 }
 
 export async function fetchContent(
@@ -77,6 +82,14 @@ export async function fetchContent(
 	signal?.addEventListener("abort", onAbort, { once: true });
 
 	try {
+		const xTarget = parseXUrl(normalized.url);
+		const xBrowser = xTarget ? await options.xBrowser?.select(controller.signal) : undefined;
+		const xDefaultMode = xTarget ? xBrowser?.mode ?? "auto" : "direct";
+		// A persistent user-selected direct-only policy cannot be overridden by a tool call.
+		const xMode = xDefaultMode === "direct" ? "direct" : normalized.xMode ?? xDefaultMode;
+		if (xTarget && xMode !== "direct") {
+			return await fetchXContent(xTarget, xMode, normalized, controller.signal, options, maxResponseBytes, xBrowser);
+		}
 		if (parseYouTubeUrl(normalized.url) !== undefined) {
 			return await fetchYouTubeContent(normalized, controller.signal, options, options.now ?? (() => new Date()));
 		}
@@ -130,34 +143,9 @@ export async function fetchContent(
 			: documentCandidate
 				? await extractAnyDocContent(bytes, mimeType, finalUrl, controller.signal, options.documentConverter)
 				: await extractWithDeadline(decodeText(bytes, contentType, mimeType), mimeType, normalized, controller.signal);
-		const sliced = sliceOutput(extracted.content, normalized.offset, normalized.maxLength);
-		const warnings = [
-			...(extracted.fellBackToRaw ? [{ code: "raw-fallback" as const, message: "Readable extraction failed; bounded raw HTML was returned" }] : []),
-			...(sliced.truncated ? [{ code: "truncated" as const, message: sliced.pagingLimitReached ? "Content was truncated at the maximum paging offset" : "Content was truncated to the configured output bound" }] : []),
-		];
-		const title = extracted.title === undefined ? undefined : boundText(extracted.title, MAX_TITLE_LENGTH);
-
-		return {
-			url: url.url.href,
-			...(url.url.href === normalized.url ? {} : { sourceUrl: normalized.url }),
-			...(title === undefined ? {} : { title }),
-			content: sliced.content,
-			contentTrust: "untrusted",
-			...(contentType === "" ? {} : { contentType }),
-			outputFormat: extracted.outputFormat,
-			extraction: extracted.extraction,
-			...(extracted.documentFormat === undefined ? {} : { documentFormat: extracted.documentFormat }),
-			fetchedAt: (options.now ?? (() => new Date()))().toISOString(),
-			status: response.status,
-			redirectCount,
-			bytesRead: bytes.byteLength,
-			truncated: sliced.truncated,
-			offset: sliced.offset,
-			...(sliced.nextOffset === undefined ? {} : { nextOffset: sliced.nextOffset }),
-			totalCharacters: extracted.content.length,
-			warnings,
-			...(extracted.fellBackToRaw ? { fellBackToRaw: true } : {}),
-		};
+		return finishContent(extracted, normalized, {
+			url: url.url.href, ...(contentType ? { contentType } : {}), status: response.status, redirectCount, bytesRead: bytes.byteLength,
+		}, options.now);
 	} catch (error) {
 		if (timedOut && !signal?.aborted && isCanceled(error)) {
 			throw new SafeFetchError({ kind: "timeout", message: `Fetch timed out after ${timeoutMs} ms`, retryable: true, cause: error });
@@ -172,6 +160,90 @@ export async function fetchContent(
 	}
 }
 
+function finishContent(
+	extracted: ExtractedContent,
+	request: NormalizedFetchRequest,
+	metadata: Pick<FetchedContent, "url" | "contentType" | "status" | "redirectCount" | "bytesRead">,
+	now: () => Date = () => new Date(),
+	notices: readonly FetchWarning[] = [],
+): FetchedContent {
+	const sliced = sliceOutput(extracted.content, request.offset, request.maxLength);
+	return {
+		...metadata,
+		...(metadata.url === request.url ? {} : { sourceUrl: request.url }),
+		...(extracted.title === undefined ? {} : { title: boundText(extracted.title, MAX_TITLE_LENGTH) }),
+		content: sliced.content, contentTrust: "untrusted", outputFormat: extracted.outputFormat,
+		extraction: extracted.extraction, fetchedAt: now().toISOString(), truncated: sliced.truncated, offset: sliced.offset,
+		...(extracted.documentFormat === undefined ? {} : { documentFormat: extracted.documentFormat }),
+		...(sliced.nextOffset === undefined ? {} : { nextOffset: sliced.nextOffset }),
+		totalCharacters: extracted.content.length,
+		warnings: [
+			...notices,
+			...(extracted.fellBackToRaw ? [{ code: "raw-fallback" as const, message: "Readable extraction failed; bounded raw HTML was returned" }] : []),
+			...(sliced.truncated ? [{ code: "truncated" as const, message: sliced.pagingLimitReached ? "Content was truncated at the maximum paging offset" : "Content was truncated to the configured output bound" }] : []),
+		],
+		...(extracted.fellBackToRaw ? { fellBackToRaw: true } : {}),
+	};
+}
+
+async function fetchXContent(
+	target: XUrl, mode: XReadMode, request: NormalizedFetchRequest,
+	signal: AbortSignal, options: FetcherOptions, maxBytes: number, selection?: XBrowserSelection,
+): Promise<FetchedContent> {
+	if (mode === "auto" || mode === "browser") {
+		// A signed-in X page loads application bundles as well as source content.
+		// Keep explicit caller limits, but allow the existing 20 MiB hard cap by default.
+		const browser = await selection?.read(target, signal, options.maxResponseBytes ?? MAX_FETCH_RESPONSE_BYTES, options.lookup);
+		if (browser) {
+			const extracted = await extractWithDeadline(`<html><head><title></title></head><body><article>${browser.html}</article></body></html>`, "text/html", { ...request, readable: false }, signal);
+			return finishContent({ ...extracted, title: browser.title, extraction: "x-browser" }, request, {
+				url: target.url, status: 200, redirectCount: 0, bytesRead: browser.bytesRead, contentType: "text/html",
+			}, options.now, [
+				{ code: "authenticated", message: "Read in your authorized browser using its existing session; content may not be public and was not sent to FxTwitter" },
+				...(target.kind === "post" ? [{ code: "partial" as const, message: "Only loaded author posts are included; thread completeness is unknown" }] : []),
+			]);
+		}
+		if (mode === "browser") throw new SafeFetchError({ kind: "extraction", message: "X browser is not authorized. Run /search-x connect once, or use public mode for free FxTwitter reads" });
+	}
+	let bytesRead = 0;
+	let redirects = 0;
+	const read = async (url: string) => {
+		if (signal.aborted) throw new SafeFetchError({ kind: "canceled", message: "X read canceled" });
+		const remote = await fetchRemoteUrl(url, {
+			signal, lookup: options.lookup, transport: options.transport,
+			maxRedirects: url.startsWith("https://api.fxtwitter.com/") ? 0 : 5,
+			headers: { "accept-encoding": "identity" },
+		});
+		const { response } = remote;
+		redirects += remote.redirectCount;
+		if (response.status < 200 || response.status >= 300) {
+			await closeResponseBody(response.body);
+			throw new SafeFetchError({ kind: "http", status: response.status, message: `X retrieval returned HTTP ${response.status}`, retryable: response.status === 429 || response.status >= 500 });
+		}
+		const remaining = maxBytes - bytesRead;
+		const declared = parseContentLength(response.headers.get("content-length"));
+		if (remaining <= 0 || declared !== undefined && declared > remaining) {
+			await closeResponseBody(response.body);
+			throw new SafeFetchError({ kind: "responseTooLarge", message: "X retrieval exceeds the aggregate response-byte limit" });
+		}
+		const bytes = await readBoundedBody(response.body, remaining, signal);
+		bytesRead += bytes.byteLength;
+		return { bytes, url: remote.url.url.href, status: response.status, redirectCount: remote.redirectCount };
+	};
+	if (!target.postId) {
+		// Article IDs are not post IDs. Try only the supplied public page, never a
+		// guessed publishing post or a search that could return unrelated evidence.
+		const page = await read(target.url);
+		const extracted = await extractWithDeadline(new TextDecoder().decode(page.bytes), "text/html", request, signal);
+		if (extracted.extraction !== "x-article") throw new SafeFetchError({ kind: "extraction", message: "X Article body is unavailable. Provide its /handle/article/POSTID or publishing post URL, or authorize the browser with /search-x connect" });
+		return finishContent(extracted, request, { url: page.url, contentType: "text/html", status: page.status, bytesRead, redirectCount: redirects }, options.now);
+	}
+	const result = await readFxTwitter(target, read);
+	return finishContent({ content: result.content, title: result.title, outputFormat: "markdown", extraction: "fxtwitter" }, request, {
+		url: result.url, contentType: "application/json", status: 200, redirectCount: redirects, bytesRead,
+	}, options.now, result.warnings.map((message) => ({ code: "partial", message })));
+}
+
 export function validateFetchRequest(request: FetchRequest): NormalizedFetchRequest {
 	if (typeof request.url !== "string" || request.url.trim().length === 0) {
 		throw new SafeFetchError({ kind: "invalidRequest", message: "URL must not be empty" });
@@ -192,6 +264,9 @@ export function validateFetchRequest(request: FetchRequest): NormalizedFetchRequ
 	if (format !== "markdown" && format !== "text" && format !== "html") {
 		throw new SafeFetchError({ kind: "invalidRequest", message: "format is not supported" });
 	}
+	if (request.xMode !== undefined && !["auto", "public", "browser", "direct"].includes(request.xMode)) {
+		throw new SafeFetchError({ kind: "invalidRequest", message: "xMode is not supported" });
+	}
 	const maxPages = request.maxPages;
 	if (maxPages !== undefined && (!Number.isInteger(maxPages) || maxPages < 1 || maxPages > 500)) {
 		throw new SafeFetchError({ kind: "invalidRequest", message: "maxPages must be between 1 and 500" });
@@ -209,6 +284,7 @@ export function validateFetchRequest(request: FetchRequest): NormalizedFetchRequ
 		allowRawHtmlFallback: request.allowRawHtmlFallback ?? true,
 		maxPages,
 		captionLanguage,
+		xMode: request.xMode,
 	};
 }
 
@@ -270,26 +346,9 @@ async function fetchYouTubeContent(
 		language: request.captionLanguage,
 		maxOutputBytes: options.youtubeMaxOutputBytes,
 	});
-	const sliced = sliceOutput(result.text, request.offset, request.maxLength);
-	const canonicalUrl = `https://www.youtube.com/watch?v=${result.videoId}`;
-	return {
-		url: canonicalUrl,
-		...(canonicalUrl === request.url ? {} : { sourceUrl: request.url }),
-		content: sliced.content,
-		contentTrust: "untrusted",
-		contentType: "text/plain",
-		outputFormat: "text",
-		extraction: "youtube-transcript",
-		fetchedAt: now().toISOString(),
-		status: 200,
-		redirectCount: 0,
-		bytesRead: result.bytesRead,
-		truncated: sliced.truncated,
-		offset: request.offset,
-		...(sliced.nextOffset === undefined ? {} : { nextOffset: sliced.nextOffset }),
-		totalCharacters: result.text.length,
-		warnings: sliced.truncated ? [{ code: "truncated", message: "Content was truncated to the configured output bound" }] : [],
-	};
+	return finishContent({ content: result.text, outputFormat: "text", extraction: "youtube-transcript" }, request, {
+		url: `https://www.youtube.com/watch?v=${result.videoId}`, contentType: "text/plain", status: 200, redirectCount: 0, bytesRead: result.bytesRead,
+	}, now);
 }
 
 function isPdfUrl(value: string): boolean {

package/src/index.ts

@@ -1,4 +1,7 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { join } from "node:path";
+import { XBrowserAccess, type XBrowserName } from "./x-browser";
+import { SafeFetchError } from "./fetch-errors";
 import { createAnthropicProvider } from "./anthropic";
 import { createBraveProvider, BraveQuotaTracker } from "./brave";
 import { createBraveAnswersProvider } from "./brave-answers";
@@ -18,6 +21,7 @@ import { createXAIProvider } from "./xai";
 import { availableProviderHints } from "./provider-availability";
 import { registerWebResearch } from "./research-tool";
 import { registerWebSearch } from "./search-tool";
+import { loadDirectCredentials } from "./credentials";
 
 /**
  * Native grounding is selected for supported active models. Exa is the
@@ -25,8 +29,10 @@ import { registerWebSearch } from "./search-tool";
  * cheaper second metered path, and Brave is the paced last-resort keyword
  * path. Automatic availability failures may use one visible fallback.
  */
-export default function (pi: ExtensionAPI): void {
-	const braveKey = process.env.BRAVE_API_KEY;
+export default async function (pi: ExtensionAPI): Promise<void> {
+	const agentDir = getAgentDir();
+	const credentials = await loadDirectCredentials(agentDir);
+	const braveKey = credentials.BRAVE_API_KEY;
 	// Brave is a conservative last-resort path: pace starts at 1 RPS and never claims
 	// to know the account's billing balance. Set `=0` only with explicit metered
 	// opt-in when that pacing is intentionally not wanted.
@@ -40,15 +46,15 @@ export default function (pi: ExtensionAPI): void {
 	const xaiX = createXAIProvider({ tool: "x_search" });
 	const anthropic = createAnthropicProvider();
 	const meta = createMetaProvider();
-	const exaKey = process.env.EXA_API_KEY;
-	const deepseekKey = process.env.DEEPSEEK_API_KEY;
-	const parallelKey = process.env.PARALLEL_API_KEY;
-	const xToken = process.env.X_API_BEARER_TOKEN;
+	const exaKey = credentials.EXA_API_KEY;
+	const deepseekKey = credentials.DEEPSEEK_API_KEY;
+	const parallelKey = credentials.PARALLEL_API_KEY;
+	const xToken = credentials.X_API_BEARER_TOKEN;
 	const exa = createExaProvider({ apiKey: exaKey });
 	const deepseek = createDeepSeekProvider({ apiKey: deepseekKey });
 	const cloudflareUpstream = process.env.PI_SEARCH_CLOUDFLARE_PROVIDER;
 	const cloudflareAccount = process.env.CLOUDFLARE_ACCOUNT_ID;
-	const cloudflareToken = process.env.CLOUDFLARE_API_TOKEN;
+	const cloudflareToken = credentials.CLOUDFLARE_API_TOKEN;
 	// Credentials alone do not enable gateway spending or select Ceramic.
 	const cloudflareConfigured = ["ceramic", "exa", "linkup"].includes(cloudflareUpstream ?? "")
 		&& Boolean(cloudflareAccount?.trim()) && Boolean(cloudflareToken?.trim());
@@ -113,7 +119,40 @@ export default function (pi: ExtensionAPI): void {
 		parallelResponses: parallelResponsesEnabled,
 		x: xToken !== undefined && xToken.trim().length > 0,
 	});
-	registerWebSearch(pi, route, { availableProviderHints: availableHints });
-	registerWebFetch(pi);
-	registerWebResearch(pi, route, { availableProviderHints: availableHints });
+	const xBrowser = new XBrowserAccess(join(agentDir, "pi-search", "x"));
+	registerWebSearch(pi, route, { availableProviderHints: availableHints, fetcherOptions: { xBrowser } });
+	registerWebFetch(pi, { xBrowser });
+	registerWebResearch(pi, route, { availableProviderHints: availableHints, xBrowser });
+	pi.on("session_shutdown", async () => { await xBrowser.shutdown(); });
+	pi.registerCommand("search-x", {
+		description: "X access: connect [brave|chrome|chromium], disconnect, status, auto, public, or direct",
+		handler: async (args, ctx) => {
+			try {
+				const parts = args.trim().split(/\s+/).filter(Boolean);
+				const [command = "status", browser = "brave"] = parts;
+				if (parts.length > (command === "connect" ? 2 : 1)) throw new SafeFetchError({ kind: "invalidRequest", message: "Unexpected X command arguments" });
+				switch (command) {
+					case "connect": {
+						if (!ctx.hasUI) throw new SafeFetchError({ kind: "extraction", message: "Run /search-x connect in an interactive Pi session to authorize your existing browser" });
+						if (!["brave", "chrome", "chromium"].includes(browser)) throw new SafeFetchError({ kind: "invalidRequest", message: "Choose brave, chrome, or chromium" });
+						const authorized = await xBrowser.connect(() => ctx.ui.confirm("Use your existing X login", `Allow pi-search to use ${browser} for read-only X extraction? Enable remote debugging in its inspect page and approve its native connection prompt. Only temporary X tabs are used; no browser is launched and no cookies are copied.`), browser as XBrowserName);
+						ctx.ui.notify(authorized ? "Browser connected. Automatic X reads now use its existing login; no paid API is used." : "X browser authorization canceled.", "info");
+						break;
+					}
+					case "disconnect":
+						await xBrowser.disconnect();
+						ctx.ui.notify(`X browser access disabled. Your browser and X login are unchanged. ${await xBrowser.status()}`, "info");
+						break;
+					case "auto": case "public": case "direct":
+						await xBrowser.setMode(command);
+						ctx.ui.notify(await xBrowser.status(), "info");
+						break;
+					case "status": ctx.ui.notify(await xBrowser.status(), "info"); break;
+					default: ctx.ui.notify("Usage: /search-x connect [brave|chrome|chromium] | disconnect | status | auto | public | direct", "warning");
+				}
+			} catch (error) {
+				ctx.ui.notify(error instanceof SafeFetchError ? error.message : "X browser operation failed. Check remote debugging and approve the connection in your running browser.", "error");
+			}
+		},
+	});
 }

package/src/parallel-responses.ts

@@ -50,7 +50,7 @@ const capabilities: ProviderCapabilities = {
 };
 
 const profile: ProviderProfile = {
-	auth: "environment",
+	auth: "direct",
 	costModel: "usage-based",
 };
 

package/src/parallel.ts

@@ -34,7 +34,7 @@ const capabilities: ProviderCapabilities = {
 };
 
 const profile: ProviderProfile = {
-	auth: "environment",
+	auth: "direct",
 	costModel: "usage-based",
 };
 

package/src/research-tool.ts

@@ -1,4 +1,3 @@
-import { StringEnum } from "@earendil-works/pi-ai";
 import {
 	defineTool,
 	type ExtensionAPI,
@@ -6,7 +5,7 @@ import {
 	type ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
-import { Type, type Static, type TUnsafe } from "typebox";
+import { Type, type Static } from "typebox";
 import type { FetchedContent, Provider, ProviderUsage, ResearchRequest, ResearchResponse, SearchProviderSelection, SearchRequest, SearchResult, SearchWarning } from "./contracts";
 import { validateResearchBudget } from "./contracts";
 import { toolUsage } from "./grounding";
@@ -20,12 +19,12 @@ import { renderModelUrl, renderSafeUrl } from "./url-rendering";
 import { compactText, sanitizeBlock } from "./render-text";
 import { SEARCH_PROVIDER_HINT_IDS, type SearchProviderHintId } from "./contracts";
 
-const ResearchProviderSchema = StringEnum(["native", ...SEARCH_PROVIDER_HINT_IDS] as const, { description: "Provider hint; omit for automatic routing" }) as TUnsafe<"native" | SearchProviderHintId>;
+const ResearchProviderSchema = Type.Enum(["native", ...SEARCH_PROVIDER_HINT_IDS] as const, { type: "string", description: "Provider hint; omit for automatic routing" });
 
 /** Full tool schema for a given set of dispatchable provider hints. */
 function webResearchParametersFor(hints: readonly SearchProviderHintId[]) {
 	const ids = ["native", ...hints] as const;
-	const schema = StringEnum(ids as unknown as readonly string[], { description: "Provider hint; omit for automatic routing" }) as TUnsafe<"native" | SearchProviderHintId>;
+	const schema = Type.Enum(ids, { type: "string", description: "Provider hint; omit for automatic routing" });
 	return Type.Object({
 		...WebResearchParameters.properties,
 		provider: Type.Optional(schema),
@@ -457,7 +456,7 @@ export async function executeResearch(
 			} catch (error) {
 				if (error instanceof SearchToolError && error.usage !== undefined) recordUsage(error.usage, estimatedCost);
 				else if (estimatedCost > 0) warnings.push(warning("Research retained the failed call's estimated cost reservation; actual billing is unconfirmed"));
-				if (deadlineController.signal.aborted || signal?.aborted) {
+				if (deadlineController.signal.aborted || signal?.aborted || remaining(deadline) <= 1) {
 					stopReason = signal?.aborted ? "canceled" : "deadline";
 					warnings.push(warning(`Research search failed for query ${JSON.stringify(query)}: ${error instanceof Error ? error.message : String(error)}`));
 					break;
@@ -511,7 +510,7 @@ export async function executeResearch(
 						break;
 					}
 				} catch (error) {
-					if (deadlineController.signal.aborted || signal?.aborted) {
+					if (deadlineController.signal.aborted || signal?.aborted || remaining(deadline) <= 1) {
 						stopReason = signal?.aborted ? "canceled" : "deadline";
 						break;
 					}
@@ -520,7 +519,7 @@ export async function executeResearch(
 				}
 			}
 		}
-		if (deadlineController.signal.aborted && stopReason === "completed") stopReason = signal?.aborted ? "canceled" : "deadline";
+		if ((deadlineController.signal.aborted || remaining(deadline) <= 1) && stopReason === "completed") stopReason = signal?.aborted ? "canceled" : "deadline";
 		if (stopReason === "completed" && hadFailedFetch) stopReason = "partial";
 		return boundedResponse(currentResponse(), normalized.budget.maxOutputChars);
 	} finally {

package/src/search-tool.ts

@@ -1,4 +1,3 @@
-import { StringEnum } from "@earendil-works/pi-ai";
 import {
 	defineTool,
 	type ExtensionAPI,
@@ -6,7 +5,7 @@ import {
 	type ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
-import { Type, type Static, type TUnsafe } from "typebox";
+import { Type, type Static } from "typebox";
 import { SEARCH_PROVIDER_HINT_IDS, type FetchedContent, type Provider, type ProviderContext, type ProviderModel, type SearchProviderHintId, type SearchProviderSelection, type SearchRequest, type SearchResponse } from "./contracts";
 import { toFetchToolError } from "./fetch-errors";
 import { boundUtf8, fetchContent, type FetcherOptions } from "./fetcher";
@@ -36,13 +35,13 @@ import {
 } from "./search";
 import { MAX_SEARCH_DOMAIN_LENGTH } from "./search-cleanup";
 
-const SearchModeSchema = StringEnum(["auto", "keyword", "fresh"] as const, { description: "Search mode; auto selects the provider path" }) as TUnsafe<"auto" | "keyword" | "fresh">;
-const SearchProviderSchema = StringEnum(["native", ...SEARCH_PROVIDER_HINT_IDS] as const, { description: "Provider hint; omit for automatic routing" }) as TUnsafe<"native" | SearchProviderHintId>;
+const SearchModeSchema = Type.Enum(["auto", "keyword", "fresh"] as const, { type: "string", description: "Search mode; auto selects the provider path" });
+const SearchProviderSchema = Type.Enum(["native", ...SEARCH_PROVIDER_HINT_IDS] as const, { type: "string", description: "Provider hint; omit for automatic routing" });
 
 /** Build the provider-enum schema from hints this installation can dispatch. */
-function providerSchemaFor(hints: readonly SearchProviderHintId[]): TUnsafe<"native" | SearchProviderHintId> {
+function providerSchemaFor(hints: readonly SearchProviderHintId[]) {
 	const ids = ["native", ...hints] as const;
-	return StringEnum(ids as unknown as readonly string[], { description: "Provider hint; omit for automatic routing" }) as TUnsafe<"native" | SearchProviderHintId>;
+	return Type.Enum(ids, { type: "string", description: "Provider hint; omit for automatic routing" });
 }
 export const SearchDomainsSchema = Type.Object(
 	{
@@ -58,11 +57,11 @@ export const SearchDateRangeSchema = Type.Object(
 	},
 	{ description: "Optional publication date range" },
 );
-const SearchContextSizeSchema = StringEnum(["low", "medium", "high"] as const, { description: "Provider-native search context size" }) as TUnsafe<"low" | "medium" | "high">;
-const ReturnTokenBudgetSchema = StringEnum(["default", "unlimited"] as const, { description: "Provider-native returned-token budget" }) as TUnsafe<"default" | "unlimited">;
+const SearchContextSizeSchema = Type.Enum(["low", "medium", "high"] as const, { type: "string", description: "Provider-native search context size" });
+const ReturnTokenBudgetSchema = Type.Enum(["default", "unlimited"] as const, { type: "string", description: "Provider-native returned-token budget" });
 const SearchUserLocationSchema = Type.Object(
 	{
-		type: StringEnum(["approximate"] as const) as TUnsafe<"approximate">,
+		type: Type.Enum(["approximate"] as const, { type: "string" }),
 		country: Type.Optional(Type.String({ minLength: 2, maxLength: 2, description: "Two-letter ISO country code" })),
 		region: Type.Optional(Type.String({ minLength: 1, maxLength: MAX_SEARCH_LOCATION_FIELD_LENGTH })),
 		city: Type.Optional(Type.String({ minLength: 1, maxLength: MAX_SEARCH_LOCATION_FIELD_LENGTH })),
@@ -98,12 +97,12 @@ export const WebSearchParameters = Type.Object({
 	social: Type.Optional(SocialSearchSchema),
 	executionModel: Type.Optional(Type.String({ minLength: 1, maxLength: MAX_EXECUTION_MODEL_LENGTH, description: "Model id when deliberately selecting a model-mediated provider" })),
 	provider: Type.Optional(SearchProviderSchema),
-	answerMode: Type.Optional(StringEnum(["auto", "evidence"] as const, { description: "Return a provider answer when available or evidence only" }) as TUnsafe<"auto" | "evidence">),
+	answerMode: Type.Optional(Type.Enum(["auto", "evidence"] as const, { type: "string", description: "Return a provider answer when available or evidence only" })),
 	searchContextSize: Type.Optional(SearchContextSizeSchema),
 	returnTokenBudget: Type.Optional(ReturnTokenBudgetSchema),
 	externalWebAccess: Type.Optional(Type.Boolean({ description: "Allow live internet access when supported" })),
 	userLocation: Type.Optional(SearchUserLocationSchema),
-	searchContentTypes: Type.Optional(Type.Array(StringEnum(["text", "image"] as const) as TUnsafe<"text" | "image">, { minItems: 1, maxItems: MAX_SEARCH_CONTENT_TYPES })),
+	searchContentTypes: Type.Optional(Type.Array(Type.Enum(["text", "image"] as const, { type: "string" }), { minItems: 1, maxItems: MAX_SEARCH_CONTENT_TYPES })),
 	imageSettings: Type.Optional(SearchImageSettingsSchema),
 	includeContent: Type.Optional(Type.Boolean({ default: false, description: "Fetch selected result pages for source context" })),
 	contentResults: Type.Optional(Type.Integer({ minimum: 1, maximum: MAX_CONTENT_RESULTS, default: DEFAULT_CONTENT_RESULTS, description: `Number of result pages to fetch when includeContent is enabled (1-${MAX_CONTENT_RESULTS})` })),