@vitos-pizza/vitos-pizza 0.1.0

package/packages/websearch/src/dispatch.ts

@@ -0,0 +1,57 @@
+import { runBackend } from "./backends/registry.ts";
+import { getActiveBackends } from "./config.ts";
+import type { SearchResult } from "./types.ts";
+
+export interface SearchFallbackResult {
+	results: SearchResult[];
+	backend: string;
+	errors: string[];
+}
+
+export async function runSearchWithFallback(
+	query: string,
+	numResults: number,
+	options: {
+		backend?: string;
+		signal?: AbortSignal;
+	},
+): Promise<SearchFallbackResult> {
+	const requested = options.backend ?? "auto";
+	const errors: string[] = [];
+
+	if (requested !== "auto") {
+		const results = await runBackend(
+			requested,
+			query,
+			numResults,
+			options.signal,
+		);
+		if (results.length === 0) {
+			throw new Error(`${requested} returned no results`);
+		}
+		return { results, backend: requested, errors };
+	}
+
+	const backends = getActiveBackends();
+	for (const backend of backends) {
+		try {
+			const results = await runBackend(
+				backend,
+				query,
+				numResults,
+				options.signal,
+			);
+			if (results.length > 0) {
+				return { results, backend, errors };
+			}
+			errors.push(`${backend}: returned no results`);
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			errors.push(`${backend}: ${message}`);
+		}
+	}
+
+	throw new Error(
+		`All search backends failed:\n${errors.map((entry) => `- ${entry}`).join("\n")}`,
+	);
+}

package/packages/websearch/src/formatters.ts

@@ -0,0 +1,44 @@
+import type { SearchResult } from "./types.ts";
+
+export function formatSearchResults(
+	query: string,
+	results: SearchResult[],
+	backend: string,
+): string {
+	const lines = [`# Web Search: ${query}`, "", `*Backend: ${backend}*`, ""];
+	if (results.length === 0) {
+		lines.push("No results found.");
+		return lines.join("\n");
+	}
+
+	for (const [index, result] of results.entries()) {
+		lines.push(`## ${index + 1}. ${result.title || "Untitled"}`);
+		if (result.url) {
+			lines.push(result.url);
+		}
+		if (result.snippet) {
+			lines.push("");
+			lines.push(result.snippet);
+		}
+		lines.push("");
+	}
+
+	return lines.join("\n").trimEnd();
+}
+
+export function formatReadResult(
+	url: string,
+	content: string,
+	reader: string,
+	title?: string,
+): string {
+	const lines = [
+		`# Web Read: ${title || url}`,
+		"",
+		`*Reader: ${reader}*`,
+		`*URL: ${url}*`,
+		"",
+		content.trim(),
+	];
+	return lines.join("\n").trimEnd();
+}

package/packages/websearch/src/parsers.ts

@@ -0,0 +1,75 @@
+import type { SearchResult } from "./types.ts";
+
+export function parseTavily(
+	data: Record<string, unknown>,
+	numResults: number,
+): SearchResult[] {
+	const rawResults = data.results;
+	const results = Array.isArray(rawResults) ? rawResults : [];
+	return results.slice(0, numResults).map((r) => ({
+		title: (r.title as string) || "",
+		url: (r.url as string) || "",
+		snippet: ((r.content as string) || "").slice(0, 500),
+		content: r.content as string | undefined,
+	}));
+}
+
+export function parseBrave(
+	data: Record<string, unknown>,
+	numResults: number,
+): SearchResult[] {
+	const web = data.web;
+	if (!web || typeof web !== "object") {
+		return [];
+	}
+	const rawResults = (web as Record<string, unknown>).results;
+	const results = Array.isArray(rawResults) ? rawResults : [];
+	return results.slice(0, numResults).map((r) => ({
+		title: (r.title as string) || "",
+		url: (r.url as string) || "",
+		snippet: ((r.description as string) || "").slice(0, 500),
+	}));
+}
+
+export function parseFirecrawl(
+	data: Record<string, unknown>,
+	numResults: number,
+): SearchResult[] {
+	const rawData = data.data;
+	let results: Array<Record<string, unknown>> = [];
+	if (Array.isArray(rawData)) {
+		results = rawData;
+	} else if (typeof rawData === "object" && rawData !== null) {
+		const obj = rawData as Record<string, unknown>;
+		results = Array.isArray(obj.web) ? obj.web : [];
+		if (results.length === 0 && Array.isArray(obj.news)) {
+			results = obj.news as Array<Record<string, unknown>>;
+		}
+	} else if (Array.isArray(data.results)) {
+		results = data.results;
+	}
+	return results.slice(0, numResults).map((r) => ({
+		title: (r.title as string) || "",
+		url: (r.url as string) || "",
+		snippet: ((r.description as string) || (r.snippet as string) || "").slice(
+			0,
+			500,
+		),
+	}));
+}
+
+export function parseExaMcpItems(
+	items: Array<Record<string, unknown>>,
+): SearchResult[] {
+	return items.map((item) => ({
+		title: (item.title as string) || "",
+		url: (item.url as string) || "",
+		snippet: (
+			(item.snippet as string) ||
+			(item.description as string) ||
+			(item.content as string) ||
+			""
+		).slice(0, 500),
+		content: item.content as string | undefined,
+	}));
+}

package/packages/websearch/src/readers/jina.ts

@@ -0,0 +1,42 @@
+import { resolveBackendKey } from "../credentials.ts";
+import type { SearchConfig } from "../types.ts";
+import { readResponseText, sanitizeError, timeoutSignal } from "../utils.ts";
+
+export async function readWithJina(
+	url: string,
+	searchConfig: SearchConfig,
+	signal?: AbortSignal,
+): Promise<{ title: string; url: string; content: string }> {
+	const readerUrl = new URL(`https://r.jina.ai/${url}`);
+	const headers: Record<string, string> = {
+		Accept: "text/plain",
+	};
+
+	const jinaKey = resolveBackendKey("jina", searchConfig);
+	if (jinaKey) {
+		headers.Authorization = `Bearer ${jinaKey}`;
+	}
+
+	const response = await fetch(readerUrl.toString(), {
+		signal: timeoutSignal(signal),
+		headers,
+	});
+
+	if (!response.ok) {
+		const text = await response.text().catch(() => "");
+		throw new Error(`Jina Reader ${sanitizeError(response.status, text)}`);
+	}
+
+	const content = await readResponseText(response);
+	const title = extractJinaTitle(content) || "";
+	return {
+		title,
+		url,
+		content,
+	};
+}
+
+function extractJinaTitle(content: string): string | undefined {
+	const match = content.match(/^Title:\s*(.+)$/m);
+	return match?.[1]?.trim();
+}

package/packages/websearch/src/schema.ts

@@ -0,0 +1,37 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { type TSchema, Type } from "typebox";
+
+export const WebSearchParams: TSchema = Type.Object({
+	query: Type.String({
+		description: "Search query (natural language works best)",
+	}),
+	numResults: Type.Optional(
+		Type.Number({
+			description: "Number of results (1-20, default 5)",
+			default: 5,
+		}),
+	),
+	backend: Type.Optional(
+		StringEnum(["auto", "exa_mcp", "firecrawl", "tavily", "brave"] as const, {
+			description:
+				"Search backend. 'auto' tries enabled backends in order (default).",
+			default: "auto",
+		}),
+	),
+});
+
+export type WebSearchInput = {
+	query: string;
+	numResults?: number;
+	backend?: "auto" | "exa_mcp" | "firecrawl" | "tavily" | "brave";
+};
+
+export const WebReadParams: TSchema = Type.Object({
+	url: Type.String({
+		description: "HTTP(S) URL to fetch as markdown",
+	}),
+});
+
+export type WebReadInput = {
+	url: string;
+};

package/packages/websearch/src/status.ts

@@ -0,0 +1,103 @@
+import { fetchExaMCP } from "./backends/exa-mcp.ts";
+import { fetchFirecrawl } from "./backends/firecrawl.ts";
+import { resolveBackendKey } from "./credentials.ts";
+import { readWithJina } from "./readers/jina.ts";
+import type { SearchConfig } from "./types.ts";
+
+export async function readUrlWithFallback(
+	url: string,
+	searchConfig: SearchConfig,
+	signal?: AbortSignal,
+): Promise<{ title: string; url: string; content: string; reader: string }> {
+	const reader = searchConfig.reader ?? "jina";
+	const errors: string[] = [];
+
+	if (reader === "exa_mcp") {
+		try {
+			const result = await fetchExaMCP(url, signal);
+			return { ...result, reader: "exa_mcp" };
+		} catch (error) {
+			errors.push(
+				`exa_mcp: ${error instanceof Error ? error.message : String(error)}`,
+			);
+		}
+	} else {
+		try {
+			const result = await readWithJina(url, searchConfig, signal);
+			return { ...result, reader: "jina" };
+		} catch (error) {
+			errors.push(
+				`jina: ${error instanceof Error ? error.message : String(error)}`,
+			);
+		}
+	}
+
+	try {
+		const firecrawlKey = resolveBackendKey("firecrawl", searchConfig);
+		const result = await fetchFirecrawl(url, firecrawlKey, signal);
+		return { ...result, reader: "firecrawl" };
+	} catch (error) {
+		errors.push(
+			`firecrawl: ${error instanceof Error ? error.message : String(error)}`,
+		);
+	}
+
+	if (reader !== "exa_mcp") {
+		try {
+			const result = await fetchExaMCP(url, signal);
+			return { ...result, reader: "exa_mcp" };
+		} catch (error) {
+			errors.push(
+				`exa_mcp: ${error instanceof Error ? error.message : String(error)}`,
+			);
+		}
+	}
+
+	throw new Error(
+		`All web_read backends failed:\n${errors.map((entry) => `- ${entry}`).join("\n")}`,
+	);
+}
+
+export function normalizeUrl(url: string): string {
+	return url.startsWith("http://") || url.startsWith("https://")
+		? url
+		: `https://${url}`;
+}
+
+export function buildSearchStatus(
+	searchConfig: SearchConfig,
+	activeBackends: string[],
+): string {
+	const lines = [
+		"# Web Search Status",
+		"",
+		`Default backend: ${searchConfig.defaultBackend ?? "auto"}`,
+		`Reader: ${searchConfig.reader ?? "jina"}`,
+		"",
+		"## Active backends",
+	];
+
+	if (activeBackends.length === 0) {
+		lines.push("- (none)");
+	} else {
+		for (const backend of activeBackends) {
+			const keyState =
+				backend === "exa_mcp"
+					? "no key required"
+					: backend === "firecrawl"
+						? resolveBackendKey("firecrawl", searchConfig)
+							? "key configured"
+							: "keyless"
+						: resolveBackendKey(backend, searchConfig)
+							? "key configured"
+							: "missing key";
+			lines.push(`- ${backend}: enabled (${keyState})`);
+		}
+	}
+
+	lines.push("", "Config paths:");
+	lines.push("- Global: ~/.pi/agent/extensions/search.json");
+	lines.push("- Project: .pi/search.json");
+
+	return lines.join("\n");
+}

package/packages/websearch/src/types.ts

@@ -0,0 +1,29 @@
+export interface SearchResult {
+	title: string;
+	url: string;
+	snippet: string;
+	content?: string;
+	backend?: string;
+}
+
+export interface BackendConfig {
+	enabled?: boolean;
+	apiKey?: string;
+}
+
+export interface SearchConfig {
+	defaultBackend?: string;
+	reader?: "jina" | "exa_mcp";
+	backends?: Record<string, BackendConfig>;
+}
+
+export interface BackendRunner {
+	needsKey: boolean;
+	optionalKey: boolean;
+	label: string;
+	search: (
+		query: string,
+		numResults: number,
+		options: { key?: string; signal?: AbortSignal },
+	) => Promise<{ results: SearchResult[] }>;
+}

package/packages/websearch/src/utils.ts

@@ -0,0 +1,117 @@
+import { isIP } from "node:net";
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+const READ_MAX_BYTES = 2 * 1024 * 1024;
+
+export function getAgentDir(): string {
+	const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
+	return `${home}/.pi/agent`.replace(/\\/g, "/");
+}
+
+export function timeoutSignal(
+	parent?: AbortSignal,
+	timeoutMs = DEFAULT_TIMEOUT_MS,
+): AbortSignal {
+	if (parent?.aborted) {
+		return AbortSignal.abort(parent.reason);
+	}
+	const controller = new AbortController();
+	const timer = setTimeout(
+		() => controller.abort(new Error("Request timed out")),
+		timeoutMs,
+	);
+	const onAbort = () => {
+		clearTimeout(timer);
+		controller.abort(parent?.reason);
+	};
+	parent?.addEventListener("abort", onAbort, { once: true });
+	controller.signal.addEventListener(
+		"abort",
+		() => {
+			clearTimeout(timer);
+			parent?.removeEventListener("abort", onAbort);
+		},
+		{ once: true },
+	);
+	return controller.signal;
+}
+
+export function sanitizeError(status: number, body: string): string {
+	const trimmed = body
+		.trim()
+		.slice(0, 200)
+		.replace(/sk-[A-Za-z0-9_-]+/g, "[redacted]");
+	return trimmed ? `HTTP ${status}: ${trimmed}` : `HTTP ${status}`;
+}
+
+function isPrivateIpv4(host: string): boolean {
+	const parts = host.split(".").map((part) => Number(part));
+	if (parts.length !== 4 || parts.some((part) => Number.isNaN(part))) {
+		return false;
+	}
+	const [a, b] = parts;
+	if (a === 10) return true;
+	if (a === 127) return true;
+	if (a === 0) return true;
+	if (a === 169 && b === 254) return true;
+	if (a === 172 && b >= 16 && b <= 31) return true;
+	if (a === 192 && b === 168) return true;
+	return false;
+}
+
+function isPrivateIpv6(host: string): boolean {
+	const normalized = host.toLowerCase();
+	if (normalized === "::1" || normalized === "::") return true;
+	if (normalized.startsWith("fc") || normalized.startsWith("fd")) return true;
+	if (normalized.startsWith("fe80")) return true;
+	return false;
+}
+
+export function validateUrl(url: string): string | null {
+	let parsed: URL;
+	try {
+		parsed = new URL(url);
+	} catch {
+		return "Invalid URL";
+	}
+	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+		return "Only HTTP(S) URLs are allowed";
+	}
+	const host = parsed.hostname.replace(/^\[|\]$/g, "");
+	if (
+		host === "localhost" ||
+		host.endsWith(".localhost") ||
+		host.endsWith(".local")
+	) {
+		return "Localhost URLs are not allowed";
+	}
+	const ipVersion = isIP(host);
+	if (ipVersion === 4 && isPrivateIpv4(host)) {
+		return "Private network URLs are not allowed";
+	}
+	if (ipVersion === 6 && isPrivateIpv6(host)) {
+		return "Private network URLs are not allowed";
+	}
+	return null;
+}
+
+export async function readResponseText(
+	response: Response,
+	maxBytes = READ_MAX_BYTES,
+): Promise<string> {
+	const contentLength = Number.parseInt(
+		response.headers.get("content-length") ?? "",
+		10,
+	);
+	if (Number.isFinite(contentLength) && contentLength > maxBytes) {
+		throw new Error(`Response too large (${contentLength} bytes)`);
+	}
+	const text = await response.text();
+	if (text.length > maxBytes) {
+		throw new Error(`Response too large (${text.length} bytes)`);
+	}
+	return text;
+}
+
+export const MISSING_KEY_HELP =
+	"Configure API keys in ~/.pi/agent/extensions/search.json or .pi/search.json";

package/packages/websearch/tsconfig.json

@@ -0,0 +1,13 @@
+{
+	"extends": "../../tsconfig.base.json",
+	"compilerOptions": {
+		"allowImportingTsExtensions": true
+	},
+	"include": [
+		"extensions/**/*.ts",
+		"src/**/*.ts",
+		"tests/**/*.ts",
+		"vitest.config.ts"
+	],
+	"exclude": ["node_modules"]
+}

package/packages/websearch/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+	test: {
+		environment: "node",
+		include: ["tests/**/*.test.ts"],
+	},
+});