@xl0/pi-lovely-web 0.1.4 → 0.2.2

package/extensions/lovely-web/find.ts

@@ -0,0 +1,356 @@
+export type FindMode = "exact" | "lower" | "fuzzy"
+
+export const FIND_HIGHLIGHT_START = "\uE000"
+export const FIND_HIGHLIGHT_END = "\uE001"
+
+const FIND_TEXT_CONTEXT_CHARS = 500
+const FIND_TEXT_SNIPPET_CHARS = FIND_TEXT_CONTEXT_CHARS * 2
+const FIND_TEXT_MAX_CHARS = FIND_TEXT_SNIPPET_CHARS * 20
+
+interface SnippetRange {
+	start: number
+	end: number
+}
+
+interface TextMatch {
+	query: string
+	index: number
+	length: number
+	highlights?: SnippetRange[]
+}
+
+interface FindSnippet extends SnippetRange {
+	matches: TextMatch[]
+}
+
+interface TextToken extends SnippetRange {
+	normalized: string
+}
+
+interface OffsetMappedText {
+	text: string
+	offsets: SnippetRange[]
+}
+
+function compactSnippetPart(text: string): string {
+	return text.replace(/\s+/g, " ").trim()
+}
+
+function snippetRange(text: string, index: number, length: number): SnippetRange {
+	return {
+		start: Math.max(0, index - FIND_TEXT_CONTEXT_CHARS),
+		end: Math.min(text.length, index + length + FIND_TEXT_CONTEXT_CHARS)
+	}
+}
+
+function mergeRanges(ranges: SnippetRange[]): SnippetRange[] {
+	const sorted = [...ranges].sort((a, b) => a.start - b.start || a.end - b.end)
+	const merged: SnippetRange[] = []
+	for (const range of sorted) {
+		const last = merged.at(-1)
+		if (!last || range.start > last.end) merged.push({ ...range })
+		else last.end = Math.max(last.end, range.end)
+	}
+	return merged
+}
+
+function mergeMatchesIntoSnippets(text: string, matches: TextMatch[]): FindSnippet[] {
+	const sorted = [...matches].sort((a, b) => a.index - b.index || a.query.localeCompare(b.query))
+	const merged: FindSnippet[] = []
+	for (const match of sorted) {
+		const range = snippetRange(text, match.index, match.length)
+		const last = merged.at(-1)
+		if (!last || range.start > last.end) merged.push({ ...range, matches: [match] })
+		else {
+			last.end = Math.max(last.end, range.end)
+			last.matches.push(match)
+		}
+	}
+	return merged
+}
+
+function matchHighlights(match: TextMatch): SnippetRange[] {
+	return match.highlights ?? [{ start: match.index, end: match.index + match.length }]
+}
+
+function formatPlainSnippet(text: string, snippet: FindSnippet): string {
+	return `${snippet.start > 0 ? "…" : ""}${compactSnippetPart(text.slice(snippet.start, snippet.end))}${snippet.end < text.length ? "…" : ""}`.trim()
+}
+
+function formatMarkedSnippet(text: string, snippet: FindSnippet): string {
+	const highlights = mergeRanges(
+		snippet.matches
+			.flatMap(match => matchHighlights(match))
+			.map(range => ({ start: Math.max(snippet.start, range.start), end: Math.min(snippet.end, range.end) }))
+			.filter(range => range.end > range.start)
+	)
+
+	let cursor = snippet.start
+	let marked = ""
+	for (const range of highlights) {
+		marked += text.slice(cursor, range.start)
+		marked += `${FIND_HIGHLIGHT_START}${text.slice(range.start, range.end)}${FIND_HIGHLIGHT_END}`
+		cursor = range.end
+	}
+	marked += text.slice(cursor, snippet.end)
+	return `${snippet.start > 0 ? "…" : ""}${compactSnippetPart(marked)}${snippet.end < text.length ? "…" : ""}`.trim()
+}
+
+function normalizeFindText(text: string): string {
+	return text
+		.normalize("NFD")
+		.replace(/\p{Diacritic}/gu, "")
+		.toLocaleLowerCase()
+}
+
+function lowerWithOffsetMap(text: string): OffsetMappedText {
+	let loweredText = ""
+	const offsets: SnippetRange[] = []
+	let index = 0
+	for (const char of text) {
+		const lowered = char.toLocaleLowerCase()
+		const end = index + char.length
+		loweredText += lowered
+		for (let i = 0; i < lowered.length; i++) offsets.push({ start: index, end })
+		index = end
+	}
+	return { text: loweredText, offsets }
+}
+
+function normalizeQuery(text: string): string {
+	return normalizeFindText(text)
+		.replace(/[^\p{L}\p{N}]+/gu, " ")
+		.replace(/\s+/g, " ")
+		.trim()
+}
+
+function tokenize(text: string, baseStart = 0): TextToken[] {
+	const tokens: TextToken[] = []
+	const re = /[\p{L}\p{N}]+/gu
+	let match = re.exec(text)
+	while (match) {
+		const raw = match[0]
+		const normalized = normalizeFindText(raw)
+		if (normalized) tokens.push({ normalized, start: baseStart + match.index, end: baseStart + match.index + raw.length })
+		match = re.exec(text)
+	}
+	return tokens
+}
+
+function cappedEditDistance(a: string, b: string, max: number): number {
+	if (Math.abs(a.length - b.length) > max) return max + 1
+	let prev = Array.from({ length: b.length + 1 }, (_, i) => i)
+	for (let i = 1; i <= a.length; i++) {
+		const curr = [i]
+		let rowMin = curr[0] ?? 0
+		for (let j = 1; j <= b.length; j++) {
+			const cost = a[i - 1] === b[j - 1] ? 0 : 1
+			const value = Math.min((prev[j] ?? 0) + 1, (curr[j - 1] ?? 0) + 1, (prev[j - 1] ?? 0) + cost)
+			curr[j] = value
+			rowMin = Math.min(rowMin, value)
+		}
+		if (rowMin > max) return max + 1
+		prev = curr
+	}
+	return prev[b.length] ?? max + 1
+}
+
+function fuzzyTokenMatches(token: string, chunkToken: string): boolean {
+	if (chunkToken === token) return true
+	if (/\d/.test(token)) return false
+	if (token.length < 6) return false
+	const maxDistance = token.length <= 8 ? 1 : 2
+	return Math.abs(token.length - chunkToken.length) <= maxDistance && cappedEditDistance(token, chunkToken, maxDistance) <= maxDistance
+}
+
+function matchingQueryIndexes(token: string, queryTokens: string[]): number[] {
+	return queryTokens.flatMap((queryToken, index) => (fuzzyTokenMatches(queryToken, token) ? [index] : []))
+}
+
+function selectFuzzyWindow(tokens: TextToken[], queryTokens: string[], maxSpan: number): { tokens: TextToken[]; coverage: number } {
+	const candidates = tokens
+		.map(token => ({ token, queryIndexes: matchingQueryIndexes(token.normalized, queryTokens) }))
+		.filter(candidate => candidate.queryIndexes.length > 0)
+	const minCoverage = queryTokens.length === 1 ? 1 : Math.ceil(queryTokens.length * 0.6)
+	for (let target = queryTokens.length; target >= minCoverage; target--) {
+		const counts = new Map<number, number>()
+		let unique = 0
+		let left = 0
+		let best: { left: number; right: number; span: number } | undefined
+		for (let right = 0; right < candidates.length; right++) {
+			for (const queryIndex of candidates[right]?.queryIndexes ?? []) {
+				const count = counts.get(queryIndex) ?? 0
+				if (count === 0) unique++
+				counts.set(queryIndex, count + 1)
+			}
+			while (unique >= target) {
+				const leftToken = candidates[left]?.token
+				const rightToken = candidates[right]?.token
+				if (leftToken && rightToken) {
+					const span = rightToken.end - leftToken.start
+					if (!best || span < best.span) best = { left, right, span }
+				}
+				for (const queryIndex of candidates[left]?.queryIndexes ?? []) {
+					const count = (counts.get(queryIndex) ?? 0) - 1
+					if (count === 0) {
+						counts.delete(queryIndex)
+						unique--
+					} else counts.set(queryIndex, count)
+				}
+				left++
+			}
+		}
+		if (best && best.span <= maxSpan) {
+			return {
+				tokens: candidates.slice(best.left, best.right + 1).map(candidate => candidate.token),
+				coverage: target / queryTokens.length
+			}
+		}
+	}
+	return { tokens: [], coverage: 0 }
+}
+
+function splitChunks(text: string): Array<{ text: string; start: number }> {
+	const chunks: Array<{ text: string; start: number }> = []
+	const re = /\n\s*\n+/g
+	let start = 0
+	let match = re.exec(text)
+	while (match) {
+		const chunkText = text.slice(start, match.index)
+		const trimmed = chunkText.trim()
+		const firstNonSpace = chunkText.search(/\S/)
+		if (trimmed.length > 20 && firstNonSpace >= 0) chunks.push({ text: trimmed, start: start + firstNonSpace })
+		start = re.lastIndex
+		match = re.exec(text)
+	}
+	const chunkText = text.slice(start)
+	const trimmed = chunkText.trim()
+	const firstNonSpace = chunkText.search(/\S/)
+	if (trimmed.length > 20 && firstNonSpace >= 0) chunks.push({ text: trimmed, start: start + firstNonSpace })
+	return chunks
+}
+
+function snippetChars(range: SnippetRange): number {
+	return range.end - range.start
+}
+
+function clipSnippet(snippet: FindSnippet, maxChars: number): FindSnippet | undefined {
+	const end = Math.min(snippet.end, snippet.start + maxChars)
+	const matches = snippet.matches.filter(match => match.index < end && match.index + match.length > snippet.start)
+	return matches.length > 0 ? { start: snippet.start, end, matches } : undefined
+}
+
+function countQueries(matches: TextMatch[]): Array<{ query: string; count: number }> {
+	const counts = new Map<string, number>()
+	for (const match of matches) counts.set(match.query, (counts.get(match.query) ?? 0) + 1)
+	return [...counts].map(([query, count]) => ({ query, count }))
+}
+
+function formatQueryCounts(matches: TextMatch[]): string {
+	return countQueries(matches)
+		.map(({ query, count }) => `"${query}" ×${count}`)
+		.join(", ")
+}
+
+function collectLiteralMatches(text: string, query: string, mode: "exact" | "lower"): TextMatch[] {
+	const needle = query.trim()
+	const lowered = mode === "lower" ? lowerWithOffsetMap(text) : undefined
+	const haystack = lowered?.text ?? text
+	const searchNeedle = mode === "exact" ? needle : needle.toLocaleLowerCase()
+	const matches: TextMatch[] = []
+	let index = searchNeedle ? haystack.indexOf(searchNeedle) : -1
+	while (index !== -1) {
+		const start = lowered?.offsets[index]?.start ?? index
+		const end = lowered?.offsets[index + searchNeedle.length - 1]?.end ?? index + needle.length
+		matches.push({ query: needle, index: start, length: end - start })
+		index = haystack.indexOf(searchNeedle, index + searchNeedle.length)
+	}
+	return matches
+}
+
+function collectFuzzyMatches(text: string, query: string): TextMatch[] {
+	const normalizedQuery = normalizeQuery(query)
+	const queryTokens = [...new Set(normalizedQuery.split(" ").filter(token => token.length >= 2))].slice(0, 20)
+	if (queryTokens.length === 0) return []
+	const maxSpan = queryTokens.length <= 2 ? Math.max(60, normalizedQuery.length * 3) : Math.max(30, queryTokens.join(" ").length * 2)
+
+	return splitChunks(text)
+		.map(chunk => {
+			const tokens = tokenize(chunk.text, chunk.start)
+			const normalizedChunk = tokens.map(token => token.normalized).join(" ")
+			const phraseHit = normalizedChunk.includes(queryTokens.join(" "))
+			const window = selectFuzzyWindow(tokens, queryTokens, maxSpan)
+			const matchedTokens = window.tokens
+			const coverage = window.coverage
+			return { chunk, matchedTokens, phraseHit, coverage, score: coverage + (phraseHit ? 1 : 0) }
+		})
+		.filter(match => match.phraseHit || (queryTokens.length === 1 ? match.coverage > 0 : match.coverage >= 0.6))
+		.sort((a, b) => b.score - a.score || a.chunk.start - b.chunk.start)
+		.map(match => {
+			const highlights = mergeRanges(match.matchedTokens.map(token => ({ start: token.start, end: token.end })))
+			const start = highlights[0]?.start ?? match.chunk.start
+			const end = highlights.at(-1)?.end ?? Math.min(text.length, match.chunk.start + 80)
+			return { query, index: start, length: end - start, highlights }
+		})
+}
+
+export function formatFindTextMatches(
+	text: string,
+	queries: string[],
+	mode: FindMode
+): { text: string; renderText: string; details: unknown } {
+	const trimmedQueries = queries.map(query => query.trim()).filter(Boolean)
+	const matches = trimmedQueries.flatMap(query =>
+		mode === "fuzzy" ? collectFuzzyMatches(text, query) : collectLiteralMatches(text, query, mode)
+	)
+	const queryResults = trimmedQueries.map(query => ({ query, matchCount: matches.filter(match => match.query === query).length }))
+	const snippets = mergeMatchesIntoSnippets(text, matches)
+	const selected: FindSnippet[] = []
+	let charsUsed = 0
+	for (const snippet of snippets) {
+		const remaining = FIND_TEXT_MAX_CHARS - charsUsed
+		if (remaining <= 0) break
+		const chars = snippetChars(snippet)
+		if (chars <= remaining) {
+			selected.push(snippet)
+			charsUsed += chars
+			continue
+		}
+		const clipped = clipSnippet(snippet, remaining)
+		if (clipped) {
+			selected.push(clipped)
+			charsUsed += snippetChars(clipped)
+		}
+		break
+	}
+	const shownMatches = selected.reduce((sum, snippet) => sum + snippet.matches.length, 0)
+	const noMatchQueries = queryResults.filter(result => result.matchCount === 0).map(result => `"${result.query}"`)
+	const title = matches.length ? `Text matches (${mode}):` : `Text matches (${mode}): no matches`
+	const body = selected.map((snippet, i) => `${i + 1}. ${formatQueryCounts(snippet.matches)}\n${formatPlainSnippet(text, snippet)}`)
+	const renderBody = selected.map((snippet, i) => `${i + 1}. ${formatQueryCounts(snippet.matches)}\n${formatMarkedSnippet(text, snippet)}`)
+	const noMatches = noMatchQueries.length ? `No matches: ${noMatchQueries.join(", ")}` : undefined
+	if (noMatches) {
+		body.push(noMatches)
+		renderBody.push(noMatches)
+	}
+	return {
+		text: body.length ? `${title}\n\n${body.join("\n\n")}` : title,
+		renderText: renderBody.length ? `${title}\n\n${renderBody.join("\n\n")}` : title,
+		details: {
+			mode,
+			contextChars: FIND_TEXT_CONTEXT_CHARS,
+			snippetChars: FIND_TEXT_SNIPPET_CHARS,
+			maxChars: FIND_TEXT_MAX_CHARS,
+			charsUsed,
+			matchCount: matches.length,
+			returnedMatches: shownMatches,
+			queryResults,
+			snippets: selected.map(snippet => ({
+				start: snippet.start,
+				end: snippet.end,
+				chars: snippetChars(snippet),
+				matches: countQueries(snippet.matches)
+			}))
+		}
+	}
+}

package/extensions/lovely-web/format.ts

@@ -15,6 +15,17 @@ function truncate(text: string, maxLen: number): string {
 	return `${text.slice(0, maxLen)}…`
 }
 
+function indent(text: string): string {
+	return text
+		.split("\n")
+		.map(line => `     ${line}`)
+		.join("\n")
+}
+
+function field(label: string, value: string): string[] {
+	return value.includes("\n") ? [`   ${label}:`, indent(value)] : [`   ${label}: ${value}`]
+}
+
 export function formatSearchOutput(results: SearchResult[]) {
 	if (results.length === 0) return "No results."
 
@@ -24,13 +35,13 @@ export function formatSearchOutput(results: SearchResult[]) {
 			const url = result.url
 			const description = result.description
 			const markdown = result.markdown?.trim()
-			const lines = [`${index + 1}. ${title}`]
+			const lines = [`${index + 1}.`, ...field("title", title)]
 
-			if (url) lines.push(`   ${url}`)
+			if (url) lines.push(...field("url", url))
 			if (description && !(index === 0 && markdown)) {
-				lines.push(`   ${truncate(description, MAX_DESCRIPTION_LENGTH)}`)
+				lines.push(...field("desc", truncate(description, MAX_DESCRIPTION_LENGTH)))
 			}
-			if (index === 0 && markdown) lines.push("", "   Markdown:", markdown)
+			if (index === 0 && markdown) lines.push("   markdown:", markdown)
 
 			return lines.join("\n")
 		})

package/extensions/lovely-web/image.ts

@@ -1,7 +1,6 @@
-import { formatDimensionNote, type ResizedImage, resizeImage } from "@earendil-works/pi-coding-agent"
+import { type AgentToolResult, 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"
 
 export const DEFAULT_MAX_IMAGE_BYTES = 5_000_000
 export const MAX_IMAGE_BYTES = 20_000_000
@@ -63,6 +62,25 @@ async function fetchImageContent(
 	}
 }
 
+function textOnlyResult(text: string, details: Record<string, unknown>): AgentToolResult<unknown> {
+	return { content: [{ type: "text" as const, text }], details }
+}
+
+function imageResult(text: string, image: { data: string; mimeType: string }, details: Record<string, unknown>): AgentToolResult<unknown> {
+	return {
+		content: [
+			{ type: "text" as const, text },
+			{ type: "image" as const, data: image.data, mimeType: image.mimeType }
+		],
+		details
+	}
+}
+
+function emitResult(result: AgentToolResult<unknown>, onUpdate?: (result: AgentToolResult<unknown>) => void): AgentToolResult<unknown> {
+	onUpdate?.(result)
+	return result
+}
+
 export async function imageImpl(
 	params: {
 		url: string
@@ -72,8 +90,8 @@ export async function imageImpl(
 		maxSize?: number | undefined
 	},
 	signal?: AbortSignal,
-	onUpdate?: (result: ToolResult) => void
-): Promise<ToolResult> {
+	onUpdate?: (result: AgentToolResult<unknown>) => void
+): Promise<AgentToolResult<unknown>> {
 	const maxBytes = params.maxBytes ?? DEFAULT_MAX_IMAGE_BYTES
 	if (maxBytes > MAX_IMAGE_BYTES) throw new Error(`maxBytes cannot exceed ${MAX_IMAGE_BYTES}`)
 
@@ -81,87 +99,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,24 @@
 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 { resetSmartRuntimeState, validateSmartConfig } from "./smart.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 {
+			resetSmartRuntimeState()
+			const loaded = loadScopedConfig(ctx.cwd, ctx)
+			if (loaded.warnings.length > 0) ctx.ui.notify(loaded.warnings.map(w => `${w.path}: ${w.message}`).join("\n"), "warning")
+			const config = validateSmartConfig(loaded.value, ctx) ? loaded.value : { ...loaded.value, smartSearchEnabled: false }
+			registerLovelyWebSearchTool(pi, config)
+			registerLovelyWebStaticTools(pi, config)
+			applyToolConfig(pi, config)
+		} 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