@xl0/pi-lovely-web 0.1.3 → 0.2.1

package/extensions/lovely-web/image.ts

@@ -1,7 +1,7 @@
 import { formatDimensionNote, type ResizedImage, resizeImage } from "@earendil-works/pi-coding-agent"
 import { getImageDimensions } from "@earendil-works/pi-tui"
-import { DEFAULT_TIMEOUT_MS } from "./config.js"
-import type { ToolResult } from "./tool-impl.js"
+import { DEFAULT_TIMEOUT_MS } from "./constants.js"
+import type { ToolResult } from "./types.js"
 
 export const DEFAULT_MAX_IMAGE_BYTES = 5_000_000
 export const MAX_IMAGE_BYTES = 20_000_000
@@ -63,6 +63,25 @@ async function fetchImageContent(
 	}
 }
 
+function textOnlyResult(text: string, details: Record<string, unknown>): ToolResult {
+	return { content: [{ type: "text" as const, text }], details }
+}
+
+function imageResult(text: string, image: { data: string; mimeType: string }, details: Record<string, unknown>): ToolResult {
+	return {
+		content: [
+			{ type: "text" as const, text },
+			{ type: "image" as const, data: image.data, mimeType: image.mimeType }
+		],
+		details
+	}
+}
+
+function emitResult(result: ToolResult, onUpdate?: (result: ToolResult) => void): ToolResult {
+	onUpdate?.(result)
+	return result
+}
+
 export async function imageImpl(
 	params: {
 		url: string
@@ -81,87 +100,58 @@ export async function imageImpl(
 	if (signal?.aborted) throw new Error("Image fetch cancelled")
 
 	const originalDimensions = getImageDimensions(image.data, image.mimeType) ?? undefined
+	const downloadDetails = {
+		url: params.url,
+		mimeType: image.mimeType,
+		bytes: image.bytes,
+		contentLength: image.contentLength
+	}
 
 	if (params.resize === false) {
 		// Re-encode to sanitize, but don't downscale.
-		const validated = (await resizeImage(
-			{ type: "image", data: image.data, mimeType: image.mimeType },
-			{ maxWidth: Infinity, maxHeight: Infinity }
-		)) as ResizedImage | null
+		const validated = (await resizeImage(Buffer.from(image.data, "base64"), image.mimeType, {
+			maxWidth: Infinity,
+			maxHeight: Infinity
+		})) as ResizedImage | null
 		if (!validated) {
 			const note = `Fetched image [${image.mimeType}]\n[Image omitted: could not be decoded]`
-			const result: ToolResult = {
-				content: [{ type: "text" as const, text: note }],
-				details: {
-					url: params.url,
-					mimeType: image.mimeType,
-					bytes: image.bytes,
-					contentLength: image.contentLength
-				}
-			}
-			onUpdate?.(result)
-			return result
+			return emitResult(textOnlyResult(note, downloadDetails), onUpdate)
 		}
 		const dimensions = { widthPx: validated.width, heightPx: validated.height }
 		const note = `Fetched image [${validated.mimeType}]`
-		const result: ToolResult = {
-			content: [
-				{ type: "text" as const, text: note },
-				{ type: "image" as const, data: validated.data, mimeType: validated.mimeType }
-			],
-			details: {
-				url: params.url,
+		return emitResult(
+			imageResult(note, validated, {
+				...downloadDetails,
 				mimeType: validated.mimeType,
-				bytes: image.bytes,
-				contentLength: image.contentLength,
 				dimensions,
 				originalDimensions,
 				wasResized: validated.wasResized
-			}
-		}
-		onUpdate?.(result)
-		return result
+			}),
+			onUpdate
+		)
 	}
 
-	const resized = (await resizeImage(
-		{ type: "image", data: image.data, mimeType: image.mimeType },
-		{ maxWidth: params.maxSize ?? 2000, maxHeight: params.maxSize ?? 2000 }
-	)) as ResizedImage | null
+	const resized = (await resizeImage(Buffer.from(image.data, "base64"), image.mimeType, {
+		maxWidth: params.maxSize ?? 2000,
+		maxHeight: params.maxSize ?? 2000
+	})) as ResizedImage | null
 
 	if (!resized) {
 		const note = `Fetched image [${image.mimeType}]\n[Image omitted: could not be decoded or resized below the inline image size limit.]`
-		const result: ToolResult = {
-			content: [{ type: "text" as const, text: note }],
-			details: {
-				url: params.url,
-				mimeType: image.mimeType,
-				bytes: image.bytes,
-				contentLength: image.contentLength,
-				dimensions: originalDimensions
-			}
-		}
-		onUpdate?.(result)
-		return result
+		return emitResult(textOnlyResult(note, { ...downloadDetails, dimensions: originalDimensions }), onUpdate)
 	}
 
 	const dimensionNote = formatDimensionNote(resized)
 	const note = `Fetched image [${resized.mimeType}]${dimensionNote ? `\n${dimensionNote}` : ""}`
 	const dimensions = { widthPx: resized.width, heightPx: resized.height }
-	const result: ToolResult = {
-		content: [
-			{ type: "text" as const, text: note },
-			{ type: "image" as const, data: resized.data, mimeType: resized.mimeType }
-		],
-		details: {
-			url: params.url,
+	return emitResult(
+		imageResult(note, resized, {
+			...downloadDetails,
 			mimeType: resized.mimeType,
-			bytes: image.bytes,
-			contentLength: image.contentLength,
 			dimensions,
 			originalDimensions,
 			wasResized: resized.wasResized
-		}
-	}
-	onUpdate?.(result)
-	return result
+		}),
+		onUpdate
+	)
 }

package/extensions/lovely-web/index.ts

@@ -1,12 +1,21 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"
 import { registerLovelyWebCommand } from "./command.js"
-import { applyToolConfig, loadConfig } from "./config.js"
-import { registerLovelyWebTools } from "./tools.js"
+import { applyToolConfig, loadScopedConfig } from "./config.js"
+import { asErrorMessage } from "./format.js"
+import { registerLovelyWebSearchTool, registerLovelyWebStaticTools } from "./tools.js"
 
 export default function (pi: ExtensionAPI) {
+	registerLovelyWebStaticTools(pi)
 	pi.on("session_start", async (_event, ctx) => {
-		applyToolConfig(pi, loadConfig(ctx.cwd))
+		try {
+			const loaded = loadScopedConfig(ctx.cwd)
+			if (loaded.warnings.length > 0) ctx.ui.notify(loaded.warnings.map(w => `${w.path}: ${w.message}`).join("\n"), "warning")
+			registerLovelyWebSearchTool(pi, loaded.value)
+			registerLovelyWebStaticTools(pi, loaded.value)
+			applyToolConfig(pi, loaded.value)
+		} catch (error) {
+			ctx.ui.notify(`Lovely Web config error: ${asErrorMessage(error)}`, "error")
+		}
 	})
-	registerLovelyWebTools(pi)
 	registerLovelyWebCommand(pi)
 }

package/extensions/lovely-web/providers/brave.ts

@@ -1,8 +1,10 @@
+import { StringEnum } from "@earendil-works/pi-ai"
+import { Type } from "typebox"
+import { DEFAULT_TIMEOUT_MS } from "../constants.js"
 import { requestJson } from "./http.js"
 import type { Provider, SearchResult } from "./types.js"
 
 const BASE_URL = "https://api.search.brave.com/res/v1"
-const DEFAULT_TIMEOUT_MS = 30_000
 
 interface BraveWebResult {
 	title: string
@@ -28,6 +30,8 @@ interface BraveImageResult {
 	url: string
 	title?: string
 	description?: string
+	properties?: { url?: string }
+	thumbnail?: { src?: string }
 }
 
 interface BraveImageResponse {
@@ -53,24 +57,35 @@ function fetchJson(url: string, apiKey: string, timeout: number, signal?: AbortS
 	)
 }
 
-function buildSearchUrl(source: string | undefined, query: string, count: number): string {
-	const encodedQuery = encodeURIComponent(query)
-	if (source === "news") {
-		return `${BASE_URL}/news/search?q=${encodedQuery}&count=${count}`
-	}
-	if (source === "images") {
-		return `${BASE_URL}/images/search?q=${encodedQuery}&count=${count}`
-	}
-	return `${BASE_URL}/web/search?q=${encodedQuery}&count=${count}`
+function buildSearchUrl(
+	source: string | undefined,
+	query: string,
+	count: number,
+	opts: { country?: string; searchLang?: string; freshness?: string }
+): string {
+	const endpoint = source === "news" ? "news" : source === "images" ? "images" : "web"
+	const url = new URL(`${BASE_URL}/${endpoint}/search`)
+	url.searchParams.set("q", query)
+	url.searchParams.set("count", String(count))
+	if (opts.country) url.searchParams.set("country", opts.country.toUpperCase())
+	if (opts.searchLang) url.searchParams.set("search_lang", opts.searchLang)
+	if (opts.freshness && source !== "images") url.searchParams.set("freshness", opts.freshness)
+	return url.toString()
 }
 
 export const braveProvider: Provider = {
 	id: "brave",
 	label: "Brave Search",
 	envApiKey: "BRAVE_API_KEY",
+	searchParameters: {
+		source: Type.Optional(StringEnum(["web", "news", "images"])),
+		country: Type.Optional(Type.String({ description: "Two-letter country code, e.g. US, DE, CO, or ALL." })),
+		searchLang: Type.Optional(Type.String({ description: "Search language code, e.g. en, es, de." })),
+		freshness: Type.Optional(Type.String({ description: "Freshness filter for web/news: pd, pw, pm, py, or YYYY-MM-DDtoYYYY-MM-DD." }))
+	},
 
 	async search(apiKey, query, opts, signal) {
-		const url = buildSearchUrl(opts.source, query, opts.limit)
+		const url = buildSearchUrl(opts.source, query, opts.limit, opts)
 		const raw = await fetchJson(url, apiKey, opts.timeout ?? DEFAULT_TIMEOUT_MS, signal)
 
 		let items: SearchResult[] = []
@@ -85,9 +100,9 @@ export const braveProvider: Provider = {
 		} else if (opts.source === "images") {
 			const data = raw as BraveImageResponse
 			items = (data.results ?? []).map(item => ({
-				title: item.title || item.url,
-				url: item.url,
-				description: item.description || ""
+				title: item.title || item.properties?.url || item.url,
+				url: item.properties?.url || item.thumbnail?.src || item.url,
+				description: item.description || item.url || ""
 			}))
 		} else {
 			const data = raw as BraveWebResponse

package/extensions/lovely-web/providers/exa.ts

@@ -1,8 +1,10 @@
+import { StringEnum } from "@earendil-works/pi-ai"
+import { Type } from "typebox"
+import { DEFAULT_TIMEOUT_MS } from "../constants.js"
 import { requestJson } from "./http.js"
 import type { Provider, SearchResult } from "./types.js"
 
 const BASE_URL = "https://api.exa.ai"
-const DEFAULT_TIMEOUT_MS = 30_000
 
 interface SearchBody {
 	query: string
@@ -10,11 +12,13 @@ interface SearchBody {
 	type: string
 	contents: { summary: boolean }
 	category?: string
+	userLocation?: string
 }
 
 interface ContentsBody {
-	ids: string[]
+	urls: string[]
 	text: boolean
+	maxAgeHours?: number
 }
 
 interface ExaSearchResult {
@@ -30,11 +34,6 @@ interface ExaContentsResult {
 	text?: string
 }
 
-function sourceToCategory(source?: string): string | undefined {
-	if (source === "news") return "news"
-	return undefined
-}
-
 function stripSummaryLabel(text: string): string {
 	return text.replace(/^Summary:\s*/i, "")
 }
@@ -60,6 +59,15 @@ export const exaProvider: Provider = {
 	id: "exa",
 	label: "Exa",
 	envApiKey: "EXA_API_KEY",
+	searchParameters: {
+		category: Type.Optional(StringEnum(["company", "people", "research paper", "news", "personal site", "financial report"])),
+		country: Type.Optional(Type.String({ description: "Two-letter ISO user location for result localization, e.g. US, DE, CO." }))
+	},
+	fetchParameters: {
+		maxAgeHours: Type.Optional(
+			Type.Integer({ description: "Maximum cache age in hours; 0 fetches fresh content, -1 uses cache only.", minimum: -1, maximum: 720 })
+		)
+	},
 
 	async search(apiKey, query, opts, signal) {
 		const body: SearchBody = {
@@ -68,8 +76,9 @@ export const exaProvider: Provider = {
 			type: "auto",
 			contents: { summary: true }
 		}
-		const category = sourceToCategory(opts.source)
-		if (category) body.category = category
+		if (opts.source) throw new Error("Exa search uses category, not source. Omit category for general web search, or set category: news.")
+		if (opts.category) body.category = opts.category
+		if (opts.country) body.userLocation = opts.country
 
 		const raw = await fetchJson(`${BASE_URL}/search`, body, apiKey, opts.timeout ?? DEFAULT_TIMEOUT_MS, signal)
 		const data = (raw as { results?: ExaSearchResult[] }).results ?? []
@@ -88,9 +97,10 @@ export const exaProvider: Provider = {
 
 	async fetch(apiKey, url, opts, signal) {
 		const body: ContentsBody = {
-			ids: [url],
+			urls: [url],
 			text: true
 		}
+		if (opts.maxAgeHours !== undefined) body.maxAgeHours = opts.maxAgeHours
 
 		const raw = await fetchJson(`${BASE_URL}/contents`, body, apiKey, opts.timeout ?? DEFAULT_TIMEOUT_MS, signal)
 		const results = (raw as { results?: ExaContentsResult[] }).results

package/extensions/lovely-web/providers/firecrawl.ts

@@ -1,13 +1,19 @@
+import { StringEnum } from "@earendil-works/pi-ai"
+import { Type } from "typebox"
+import { DEFAULT_TIMEOUT_MS } from "../constants.js"
 import { requestJson } from "./http.js"
 import type { Provider, SearchResult } from "./types.js"
 
-const BASE_URL = "https://api.firecrawl.dev/v1"
-const DEFAULT_TIMEOUT_MS = 30_000
+const BASE_URL = "https://api.firecrawl.dev/v2"
 
 interface SearchBody {
 	query: string
 	limit: number
 	sources?: string[]
+	categories?: string[]
+	location?: string
+	country?: string
+	tbs?: string
 }
 
 interface ScrapeBody {
@@ -52,18 +58,43 @@ export const firecrawlProvider: Provider = {
 	id: "firecrawl",
 	label: "Firecrawl",
 	envApiKey: "FIRECRAWL_API_KEY",
+	searchParameters: {
+		source: Type.Optional(StringEnum(["web", "news", "images"])),
+		category: Type.Optional(StringEnum(["github", "research", "pdf"])),
+		location: Type.Optional(Type.String({ description: "Geo-target results, e.g. Germany or San Francisco,California,United States." })),
+		country: Type.Optional(Type.String({ description: "ISO country code for geo-targeting, e.g. US, DE, CO." })),
+		tbs: Type.Optional(Type.String({ description: "Google-style time filter, e.g. qdr:d, qdr:w, qdr:m, qdr:y." }))
+	},
+	fetchParameters: {
+		waitFor: Type.Optional(Type.Integer({ description: "Extra delay in milliseconds before capturing page content.", minimum: 0 }))
+	},
 
 	async search(apiKey, query, opts, signal) {
 		const body: SearchBody = { query, limit: opts.limit }
 		if (opts.source) body.sources = [opts.source]
+		if (opts.category) body.categories = [opts.category]
+		if (opts.location) body.location = opts.location
+		if (opts.country) body.country = opts.country
+		if (opts.tbs) body.tbs = opts.tbs
 
 		const raw = await fetchJson(`${BASE_URL}/search`, body, apiKey, opts.timeout ?? DEFAULT_TIMEOUT_MS, signal)
 		throwIfError(raw)
-		const data = raw.data as Array<{ title: string; url: string; description: string }>
+		const data = raw.data as {
+			web?: Array<{ title: string; url: string; description?: string; markdown?: string }>
+			news?: Array<{ title: string; url: string; snippet?: string; markdown?: string }>
+			images?: Array<{ title?: string; url: string; imageUrl?: string }>
+		}
+		const items = opts.source === "news" ? data.news || [] : opts.source === "images" ? data.images || [] : data.web || []
 
-		const results: SearchResult[] = data.map(item => {
-			const r: SearchResult = { title: item.title, url: item.url }
-			if (item.description) r.description = item.description
+		const results: SearchResult[] = items.map(item => {
+			const isImage = opts.source === "images"
+			const r: SearchResult = {
+				title: item.title || item.url,
+				url: isImage && "imageUrl" in item && item.imageUrl ? item.imageUrl : item.url
+			}
+			const description = "description" in item ? item.description : "snippet" in item ? item.snippet : undefined
+			if (description) r.description = description
+			if ("markdown" in item && item.markdown) r.markdown = item.markdown
 			return r
 		})
 

package/extensions/lovely-web/providers/tavily.ts

@@ -1,14 +1,20 @@
+import { StringEnum } from "@earendil-works/pi-ai"
+import { Type } from "typebox"
+import { DEFAULT_TIMEOUT_MS } from "../constants.js"
 import { requestJson } from "./http.js"
 import type { Provider, SearchResult } from "./types.js"
 
 const BASE_URL = "https://api.tavily.com"
-const DEFAULT_TIMEOUT_MS = 30_000
 
 interface SearchBody {
 	query: string
 	max_results: number
 	search_depth: string
 	topic?: string
+	time_range?: string
+	country?: string
+	include_images?: boolean
+	include_image_descriptions?: boolean
 }
 
 interface ExtractBody {
@@ -25,11 +31,16 @@ interface TavilySearchResult {
 	score: number
 }
 
+interface TavilyImageResult {
+	url: string
+	description?: string
+}
+
 interface TavilySearchResponse {
 	query: string
 	answer?: string
 	results?: TavilySearchResult[]
-	images?: unknown[]
+	images?: TavilyImageResult[]
 	response_time: number
 }
 
@@ -46,11 +57,6 @@ interface TavilyExtractResponse {
 	response_time: number
 }
 
-function sourceToTopic(source?: string): string | undefined {
-	if (source === "news") return "news"
-	return undefined
-}
-
 function postJson(url: string, body: unknown, apiKey: string, timeout: number, signal?: AbortSignal): Promise<unknown> {
 	return requestJson(
 		"Tavily",
@@ -72,6 +78,17 @@ export const tavilyProvider: Provider = {
 	id: "tavily",
 	label: "Tavily",
 	envApiKey: "TAVILY_API_KEY",
+	searchParameters: {
+		topic: Type.Optional(StringEnum(["general", "news", "finance"])),
+		includeImages: Type.Optional(Type.Boolean({ description: "Return query-related image URLs instead of page results." })),
+		country: Type.Optional(Type.String({ description: "Country name to boost general-topic results, e.g. colombia." })),
+		timeRange: Type.Optional(StringEnum(["day", "week", "month", "year", "d", "w", "m", "y"]))
+	},
+	fetchParameters: {
+		extractDepth: Type.Optional(
+			StringEnum(["basic", "advanced"], { description: "Advanced extraction retrieves more data such as tables; costs more." })
+		)
+	},
 
 	async search(apiKey, query, opts, signal) {
 		const body: SearchBody = {
@@ -79,11 +96,28 @@ export const tavilyProvider: Provider = {
 			max_results: opts.limit,
 			search_depth: "basic"
 		}
-		const topic = sourceToTopic(opts.source)
-		if (topic) body.topic = topic
+		if (opts.source) throw new Error("Tavily search uses topic/includeImages, not source.")
+		const topic = opts.topic
+		if (topic && topic !== "general") body.topic = topic
+		if (opts.timeRange) body.time_range = opts.timeRange
+		if (opts.country && topic !== "news" && topic !== "finance") body.country = opts.country.toLowerCase()
+		if (opts.includeImages) {
+			body.include_images = true
+			body.include_image_descriptions = true
+		}
 
 		const raw = await postJson(`${BASE_URL}/search`, body, apiKey, opts.timeout ?? DEFAULT_TIMEOUT_MS, signal)
 		const data = raw as TavilySearchResponse
+
+		if (opts.includeImages) {
+			const results: SearchResult[] = (data.images ?? []).map(item => ({
+				title: item.description || item.url,
+				url: item.url,
+				description: item.description || ""
+			}))
+			return { results, raw }
+		}
+
 		const items = data.results ?? []
 
 		const results: SearchResult[] = items.map(item => {
@@ -101,7 +135,7 @@ export const tavilyProvider: Provider = {
 	async fetch(apiKey, url, opts, signal) {
 		const body: ExtractBody = {
 			urls: [url],
-			extract_depth: "basic",
+			extract_depth: opts.extractDepth ?? "basic",
 			format: "markdown"
 		}
 

package/extensions/lovely-web/providers/types.ts

@@ -1,3 +1,5 @@
+import type { TSchema } from "typebox"
+
 export interface SearchResult {
 	title: string
 	url: string
@@ -5,27 +7,39 @@ export interface SearchResult {
 	markdown?: string // populated for first result when fetchResult=true
 }
 
+export interface SearchOptions {
+	limit: number
+	source?: string
+	timeout?: number
+	category?: string
+	location?: string
+	country?: string
+	tbs?: string
+	timeRange?: string
+	topic?: string
+	includeImages?: boolean
+	searchLang?: string
+	freshness?: string
+}
+
+export interface FetchOptions {
+	timeout?: number
+	waitFor?: number
+	maxAgeHours?: number
+	extractDepth?: string
+}
+
 export interface Provider {
 	readonly id: string
 	readonly label: string
 	readonly envApiKey: string
-	search(
-		apiKey: string,
-		query: string,
-		opts: { limit: number; source?: string; timeout?: number },
-		signal?: AbortSignal
-	): Promise<{ results: SearchResult[]; raw: unknown }>
+	readonly searchParameters?: Record<string, TSchema>
+	readonly fetchParameters?: Record<string, TSchema>
+	search(apiKey: string, query: string, opts: SearchOptions, signal?: AbortSignal): Promise<{ results: SearchResult[]; raw: unknown }>
 	fetch?(
 		apiKey: string,
 		url: string,
-		opts: { waitFor?: number; timeout?: number },
+		opts: FetchOptions,
 		signal?: AbortSignal
 	): Promise<{ markdown: string; metadata?: unknown; raw: unknown }>
 }
-
-export interface WebToolsConfig {
-	webSearch?: { provider?: string | null }
-	webFetch?: { provider?: string | null }
-	webImage?: { enabled?: boolean; resize?: boolean; maxSize?: number }
-	webApiKeys?: Record<string, string>
-}