@xl0/pi-lovely-web 0.1.4 → 0.2.1

package/extensions/lovely-web/tools.ts

@@ -1,14 +1,107 @@
-import { StringEnum } from "@earendil-works/pi-ai"
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"
 import { Text } from "@earendil-works/pi-tui"
-import { Type } from "typebox"
-import { getImageMaxSize, getProvider, isImageEnabled, isImageResizeEnabled, loadConfig } from "./config.js"
-import { asErrorMessage } from "./format.js"
+import { type TSchema, Type } from "typebox"
+import {
+	DEFAULT_PROVIDER_ID,
+	getImageMaxSize,
+	getProvider,
+	isFetchEnabled,
+	isImageEnabled,
+	isImageResizeEnabled,
+	loadConfig,
+	lovelyWebConfigSpec,
+	providers,
+	resolveApiKey,
+	type WebToolsConfig
+} from "./config.js"
+import { DEFAULT_TIMEOUT_MS } from "./constants.js"
+import { asErrorMessage, formatSearchOutput, stringify } from "./format.js"
 import { DEFAULT_MAX_IMAGE_BYTES, imageImpl, MAX_IMAGE_BYTES } from "./image.js"
+import type { FetchOptions, SearchOptions } from "./providers/types.js"
 import { renderTextResult } from "./render.js"
-import { fetchImpl, searchImpl } from "./tool-impl.js"
+import type { ToolResult } from "./types.js"
 
-export function registerLovelyWebTools(pi: ExtensionAPI) {
+interface SearchToolArgs {
+	query: string
+	limit?: number
+	source?: string
+	fetchResult?: boolean
+	category?: string
+	location?: string
+	country?: string
+	tbs?: string
+	timeRange?: string
+	topic?: string
+	includeImages?: boolean
+	searchLang?: string
+	freshness?: string
+}
+
+interface FetchToolArgs extends FetchOptions {
+	url: string
+	includeMetadata?: boolean
+}
+
+async function fetchSearchResultImage(config: WebToolsConfig, url: string, signal?: AbortSignal): Promise<ToolResult> {
+	return imageImpl(
+		{
+			url,
+			timeout: DEFAULT_TIMEOUT_MS,
+			resize: isImageResizeEnabled(config),
+			maxSize: getImageMaxSize(config)
+		},
+		signal
+	)
+}
+
+async function fetchSearchResultMarkdown(config: WebToolsConfig, url: string, signal?: AbortSignal): Promise<string> {
+	const fetchProvider = getProvider("fetch", config)
+	const fetchApiKey = resolveApiKey(fetchProvider, config)
+	const fetched = await fetchProvider.fetch(fetchApiKey, url, { timeout: DEFAULT_TIMEOUT_MS }, signal)
+	return fetched.markdown
+}
+
+function getSearchParameters(config: WebToolsConfig) {
+	const configured = config.webSearchProvider
+	const providerId = configured && providers[configured] ? configured : DEFAULT_PROVIDER_ID
+	const params: Record<string, TSchema> = {
+		query: Type.String({ description: "The search query." }),
+		limit: Type.Optional(
+			Type.Integer({
+				description: "Maximum number of results to return. Defaults to 5.",
+				minimum: 1,
+				maximum: 20
+			})
+		),
+		fetchResult: Type.Optional(
+			Type.Boolean({
+				description: "Whether to fetch the first result. Defaults to false; image searches fetch image content when enabled."
+			})
+		)
+	}
+
+	Object.assign(params, providers[providerId]?.searchParameters)
+	return Type.Object(params)
+}
+
+function getFetchParameters(config: WebToolsConfig) {
+	const configured = config.webFetchProvider
+	const providerId = configured && providers[configured]?.fetch ? configured : "firecrawl"
+	const params: Record<string, TSchema> = {
+		url: Type.String({ description: "The URL to fetch.", format: "uri" }),
+		timeout: Type.Optional(Type.Integer({ description: "Request timeout in milliseconds. Defaults to 30000.", minimum: 1 })),
+		includeMetadata: Type.Optional(
+			Type.Boolean({
+				description: "Append verbose page metadata to the markdown output. Defaults to false. Full metadata is always available in details."
+			})
+		)
+	}
+
+	Object.assign(params, providers[providerId]?.fetchParameters)
+	return Type.Object(params)
+}
+
+export function registerLovelyWebSearchTool(pi: ExtensionAPI, config: WebToolsConfig = lovelyWebConfigSpec.defaults) {
 	pi.registerTool({
 		name: "web_search",
 		label: "Web Search",
@@ -18,28 +111,15 @@ export function registerLovelyWebTools(pi: ExtensionAPI) {
 			"Use web_search when the user asks for current web information, discovery, or sources beyond the local workspace.",
 			"Use web_fetch after web_search when you need the full content of a specific page."
 		],
-		parameters: Type.Object({
-			query: Type.String({ description: "The web search query." }),
-			limit: Type.Optional(
-				Type.Integer({
-					description: "Maximum number of results to return. Defaults to 5.",
-					minimum: 1,
-					maximum: 20
-				})
-			),
-			source: Type.Optional(StringEnum(["web", "news", "images"] as const)),
-			fetchResult: Type.Optional(
-				Type.Boolean({
-					description: "Whether to fetch the first result and include markdown. Defaults to true."
-				})
-			)
-		}),
+		parameters: getSearchParameters(config),
 		renderCall(args, theme, context) {
 			const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0)
-			const bits = [args.source ?? "web", `limit ${args.limit ?? 5}`]
-			if (args.fetchResult ?? true) bits.push("fetch first")
+			const input = args as unknown as SearchToolArgs
+			const mode = input.includeImages ? "images" : (input.source ?? input.topic ?? input.category ?? "web")
+			const bits = [mode, `limit ${input.limit ?? 5}`]
+			if (input.fetchResult === true) bits.push("fetch first")
 			text.setText(
-				`${theme.fg("toolTitle", theme.bold("web_search "))}${theme.fg("muted", `"${args.query}"`)} ${theme.fg("dim", `(${bits.join(", ")})`)}`
+				`${theme.fg("toolTitle", theme.bold("web_search "))}${theme.fg("muted", `"${input.query}"`)} ${theme.fg("dim", `(${bits.join(", ")})`)}`
 			)
 			return text
 		},
@@ -50,11 +130,45 @@ export function registerLovelyWebTools(pi: ExtensionAPI) {
 			try {
 				const config = loadConfig(ctx.cwd)
 				const searchProvider = getProvider("search", config)
+				const input = params as unknown as SearchToolArgs
 				onUpdate?.({
-					content: [{ type: "text", text: `Searching web with ${searchProvider.label} for: ${params.query}` }],
-					details: undefined as unknown
+					content: [{ type: "text", text: `Searching web with ${searchProvider.label} for: ${input.query}` }],
+					details: undefined
 				})
-				return await searchImpl(config, params, signal, onUpdate)
+
+				const { query, fetchResult, limit, ...providerOptions } = input
+				const searchOptions: SearchOptions = { ...providerOptions, limit: limit ?? 5, timeout: DEFAULT_TIMEOUT_MS }
+				const searchResult = await searchProvider.search(resolveApiKey(searchProvider, config), query, searchOptions, signal)
+				if (signal?.aborted) throw new Error("Search cancelled")
+
+				const first = searchResult.results[0]
+				let fetchedImage: ToolResult | undefined
+				if (fetchResult === true && first?.url) {
+					onUpdate?.({ content: [{ type: "text", text: `Fetching first result: ${first.url}` }], details: undefined })
+					try {
+						const isImageSearch = input.source === "images" || input.includeImages === true
+						if (isImageSearch) {
+							try {
+								fetchedImage = await fetchSearchResultImage(config, first.url, signal)
+							} catch {
+								if (signal?.aborted) throw new Error("Search cancelled")
+								// Some image-search providers return source pages instead of direct image URLs.
+							}
+						}
+						if (!fetchedImage && isFetchEnabled(config)) first.markdown = await fetchSearchResultMarkdown(config, first.url, signal)
+						if (signal?.aborted) throw new Error("Search cancelled")
+					} catch (err) {
+						if (signal?.aborted) throw err
+						first.description = first.description || `[Fetch failed: ${asErrorMessage(err)}]`
+					}
+				}
+
+				const result: ToolResult = {
+					content: [{ type: "text", text: formatSearchOutput(searchResult.results) }, ...(fetchedImage?.content || [])],
+					details: fetchedImage ? { search: searchResult.raw, image: fetchedImage.details } : searchResult.raw
+				}
+				onUpdate?.(result)
+				return result
 			} catch (error) {
 				return {
 					content: [{ type: "text", text: `Web search failed: ${asErrorMessage(error)}` }],
@@ -64,7 +178,9 @@ export function registerLovelyWebTools(pi: ExtensionAPI) {
 			}
 		}
 	})
+}
 
+export function registerLovelyWebStaticTools(pi: ExtensionAPI, config: WebToolsConfig = lovelyWebConfigSpec.defaults) {
 	pi.registerTool({
 		name: "web_fetch",
 		label: "Web Fetch",
@@ -74,30 +190,18 @@ export function registerLovelyWebTools(pi: ExtensionAPI) {
 			"Use web_fetch when you need the full readable markdown content of a known URL.",
 			"Prefer web_fetch over bash/curl for web pages because web_fetch returns cleaned markdown suitable for agent context."
 		],
-		parameters: Type.Object({
-			url: Type.String({ description: "The URL to fetch.", format: "uri" }),
-			waitFor: Type.Optional(
-				Type.Integer({
-					description: "Milliseconds to wait before capturing content, useful for JS-heavy pages.",
-					minimum: 0
-				})
-			),
-			timeout: Type.Optional(Type.Integer({ description: "Request timeout in milliseconds. Defaults to 30000.", minimum: 1 })),
-			includeMetadata: Type.Optional(
-				Type.Boolean({
-					description:
-						"Append verbose page metadata to the markdown output. Defaults to false. Full metadata is always available in details."
-				})
-			)
-		}),
+		parameters: getFetchParameters(config),
 		renderCall(args, theme, context) {
 			const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0)
+			const input = args as unknown as FetchToolArgs
 			const bits: string[] = []
-			if (args.waitFor !== undefined) bits.push(`wait ${args.waitFor}ms`)
-			if (args.timeout !== undefined) bits.push(`timeout ${args.timeout}ms`)
-			if (args.includeMetadata) bits.push("metadata")
+			if (input.waitFor !== undefined) bits.push(`wait ${input.waitFor}ms`)
+			if (input.maxAgeHours !== undefined) bits.push(`max age ${input.maxAgeHours}h`)
+			if (input.extractDepth !== undefined) bits.push(input.extractDepth)
+			if (input.timeout !== undefined) bits.push(`timeout ${input.timeout}ms`)
+			if (input.includeMetadata) bits.push("metadata")
 			const suffix = bits.length ? ` ${theme.fg("dim", `(${bits.join(", ")})`)}` : ""
-			text.setText(`${theme.fg("toolTitle", theme.bold("web_fetch "))}${theme.fg("muted", args.url)}${suffix}`)
+			text.setText(`${theme.fg("toolTitle", theme.bold("web_fetch "))}${theme.fg("muted", input.url)}${suffix}`)
 			return text
 		},
 		renderResult(result, { expanded, isPartial }, theme) {
@@ -105,13 +209,34 @@ export function registerLovelyWebTools(pi: ExtensionAPI) {
 		},
 		async execute(_toolCallId, params, signal, onUpdate, ctx) {
 			try {
+				const input = params as unknown as FetchToolArgs
 				const config = loadConfig(ctx.cwd)
 				const fetchProvider = getProvider("fetch", config)
 				onUpdate?.({
-					content: [{ type: "text", text: `Fetching page with ${fetchProvider.label}: ${params.url}` }],
-					details: undefined as unknown
+					content: [{ type: "text", text: `Fetching page with ${fetchProvider.label}: ${input.url}` }],
+					details: undefined
 				})
-				return await fetchImpl(config, params, signal, onUpdate)
+
+				const result = await fetchProvider.fetch(
+					resolveApiKey(fetchProvider, config),
+					input.url,
+					{
+						timeout: input.timeout ?? DEFAULT_TIMEOUT_MS,
+						...(input.waitFor !== undefined ? { waitFor: input.waitFor } : {}),
+						...(input.maxAgeHours !== undefined ? { maxAgeHours: input.maxAgeHours } : {}),
+						...(input.extractDepth !== undefined ? { extractDepth: input.extractDepth } : {})
+					},
+					signal
+				)
+				if (signal?.aborted) throw new Error("Fetch cancelled")
+
+				const metadata = input.includeMetadata && result.metadata ? `\n\nMetadata:\n${stringify(result.metadata)}` : ""
+				const toolResult: ToolResult = {
+					content: [{ type: "text", text: `${result.markdown}${metadata}` }],
+					details: result.raw
+				}
+				onUpdate?.(toolResult)
+				return toolResult
 			} catch (error) {
 				return {
 					content: [{ type: "text", text: `Web fetch failed: ${asErrorMessage(error)}` }],
@@ -157,7 +282,7 @@ export function registerLovelyWebTools(pi: ExtensionAPI) {
 				if (!isImageEnabled(config)) throw new Error("web_image is disabled. Enable it via /lovely-web.")
 				onUpdate?.({
 					content: [{ type: "text", text: `Fetching image: ${params.url}` }],
-					details: undefined as unknown
+					details: undefined
 				})
 				return await imageImpl(
 					{
@@ -180,3 +305,8 @@ export function registerLovelyWebTools(pi: ExtensionAPI) {
 		}
 	})
 }
+
+export function registerLovelyWebTools(pi: ExtensionAPI, config: WebToolsConfig = lovelyWebConfigSpec.defaults) {
+	registerLovelyWebSearchTool(pi, config)
+	registerLovelyWebStaticTools(pi, config)
+}

package/extensions/lovely-web/types.ts

@@ -0,0 +1,7 @@
+import type { ImageContent, TextContent } from "@earendil-works/pi-ai"
+
+export interface ToolResult {
+	content: Array<TextContent | ImageContent>
+	details: unknown
+	isError?: boolean
+}

package/package.json

@@ -1,6 +1,7 @@
 {
 	"name": "@xl0/pi-lovely-web",
-	"version": "0.1.4",
+	"version": "0.2.1",
+	"description": "Pi extension package for web_search, web_fetch, and web_image via Firecrawl, Exa, Tavily, and Brave.",
 	"keywords": [
 		"pi-package",
 		"firecrawl",
@@ -36,14 +37,20 @@
 	},
 	"devDependencies": {
 		"@biomejs/biome": "^2.4.14",
+		"@earendil-works/pi-ai": "^0.79.10",
+		"@earendil-works/pi-coding-agent": "^0.79.10",
+		"@earendil-works/pi-tui": "^0.79.10",
 		"@typescript/native-preview": "^7.0.0-dev.20260502.1",
 		"bun-types": "^1.3.13",
 		"typescript": "^6.0.3"
 	},
+	"dependencies": {
+		"@xl0/pi-lovely-config": "^0.1.0"
+	},
 	"peerDependencies": {
-		"@earendil-works/pi-ai": ">=0.75.4",
-		"@earendil-works/pi-coding-agent": ">=0.75.4",
-		"@earendil-works/pi-tui": ">=0.75.4",
+		"@earendil-works/pi-ai": ">=0.79.10",
+		"@earendil-works/pi-coding-agent": ">=0.79.10",
+		"@earendil-works/pi-tui": ">=0.79.10",
 		"typebox": "*"
 	},
 	"pi": {

package/extensions/lovely-web/tool-impl.ts

@@ -1,95 +0,0 @@
-import type { ImageContent, TextContent } from "@earendil-works/pi-ai"
-import { DEFAULT_TIMEOUT_MS, getProvider, resolveApiKey } from "./config.js"
-import { asErrorMessage, formatSearchOutput, stringify } from "./format.js"
-import type { WebToolsConfig } from "./providers/types.js"
-
-export interface ToolResult {
-	content: Array<TextContent | ImageContent>
-	details: unknown
-	isError?: boolean
-}
-
-export async function searchImpl(
-	config: WebToolsConfig,
-	params: { query: string; limit?: number; source?: string; fetchResult?: boolean },
-	signal?: AbortSignal,
-	onUpdate?: (result: ToolResult) => void
-): Promise<ToolResult> {
-	const searchProvider = getProvider("search", config)
-	const apiKey = resolveApiKey(searchProvider, config)
-
-	const searchResult = await searchProvider.search(
-		apiKey,
-		params.query,
-		{
-			limit: params.limit ?? 5,
-			timeout: DEFAULT_TIMEOUT_MS,
-			...(params.source !== undefined ? { source: params.source } : {})
-		},
-		signal
-	)
-
-	if (signal?.aborted) throw new Error("Search cancelled")
-
-	const shouldFetch = params.fetchResult ?? true
-	const first = searchResult.results[0]
-	if (shouldFetch && first?.url) {
-		onUpdate?.({
-			content: [{ type: "text" as const, text: `Fetching first result: ${first.url}` }],
-			details: undefined as unknown
-		})
-		try {
-			const fetchProvider = getProvider("fetch", config)
-			const fetchApiKey = resolveApiKey(fetchProvider, config)
-			const fetched = await fetchProvider.fetch(fetchApiKey, first.url, { timeout: DEFAULT_TIMEOUT_MS }, signal)
-
-			if (signal?.aborted) throw new Error("Search cancelled")
-			first.markdown = fetched.markdown
-			if (fetched.metadata) (first as { metadata?: unknown }).metadata = fetched.metadata
-		} catch (err) {
-			first.description = first.description || `[Fetch failed: ${asErrorMessage(err)}]`
-		}
-	}
-
-	const result: ToolResult = {
-		content: [{ type: "text" as const, text: formatSearchOutput(searchResult.results) }],
-		details: searchResult.raw
-	}
-	onUpdate?.(result)
-	return result
-}
-
-export async function fetchImpl(
-	config: WebToolsConfig,
-	params: { url: string; waitFor?: number; timeout?: number; includeMetadata?: boolean },
-	signal?: AbortSignal,
-	onUpdate?: (result: ToolResult) => void
-): Promise<ToolResult> {
-	const fetchProvider = getProvider("fetch", config)
-	const apiKey = resolveApiKey(fetchProvider, config)
-
-	const result = await fetchProvider.fetch(
-		apiKey,
-		params.url,
-		{
-			timeout: params.timeout ?? DEFAULT_TIMEOUT_MS,
-			...(params.waitFor !== undefined ? { waitFor: params.waitFor } : {})
-		},
-		signal
-	)
-
-	if (signal?.aborted) throw new Error("Fetch cancelled")
-
-	const warning =
-		["exa", "tavily"].includes(fetchProvider.id) && params.waitFor !== undefined
-			? `Warning: ${fetchProvider.label} ignores waitFor; request sent without any extra page-load delay.\n\n`
-			: ""
-	const metadata = params.includeMetadata && result.metadata ? `\n\nMetadata:\n${stringify(result.metadata)}` : ""
-
-	const toolResult: ToolResult = {
-		content: [{ type: "text" as const, text: `${warning}${result.markdown}${metadata}` }],
-		details: result.raw
-	}
-	onUpdate?.(toolResult)
-	return toolResult
-}