@xl0/pi-lovely-web 0.1.4 → 0.2.2

package/README.md

@@ -15,31 +15,30 @@ pi install npm:@xl0/pi-lovely-web
 
 ## Tools
 
-- `web_search` - Compact search results (list of results + markdown of the first result)
-The plain-text tool output looks likes this:
+- `web_search` - Compact search results. Set `fetchResult:true` to include markdown from the first result when `web_fetch` is configured.
 
-> `web_search "pi coding agent harness earendil" (web, limit 5, fetch first)`
+The plain-text tool output looks like this:
+
+> `web_search "pi coding agent harness earendil" (web, limit 5)`
 
 ```
-1. GitHub - earendil-works/pi: AI agent toolkit
-    https://github.com/earendil-works/pi
-    Markdown:
-[markdown of the first hit if `fetch_first` is not false]
-
- 2. packages/coding-agent/README.md at main · earendil-works/pi
-    https://github.com/earendil-works/pi/blob/main/packages/coding-agent/README.md
-    The page describes the pi project from earendil-works, a minimal, extensible terminal coding harness designed to adapt to your workflow. Key points:
- - Pi is an AI agent toolkit for coding: CLI, unified LLM API, TUI/Web UI libraries, Slack bot, and vLLM pods.
- - Core idea: extendable with TypeScript E…
-
- 3. Pi Coding Agent
-    https://pi.dev/
-    Pi Coding Agent is a minimal, highly customizable terminal coding harness. It adapts to your workflow with extensible packages (extensions, skills, prompts, and themes) that you can bundle
- and share via npm or git. Key ideas:
- - Four modes: interactive TUI, print/JSON, RPC, and SDK (usable for embedd…
+1.
+   title: GitHub - earendil-works/pi: AI agent toolkit
+   url: https://github.com/earendil-works/pi
+   desc: Pi is an AI agent toolkit for coding: CLI, unified LLM API, TUI/Web UI libraries, Slack bot, and vLLM pods.
+
+2.
+   title: packages/coding-agent/README.md at main · earendil-works/pi
+   url: https://github.com/earendil-works/pi/blob/main/packages/coding-agent/README.md
+   desc: The page describes the pi project from earendil-works, a minimal, extensible terminal coding harness designed to adapt to your workflow.
+
+3.
+   title: Pi Coding Agent
+   url: https://pi.dev/
+   desc: Pi Coding Agent is a minimal, highly customizable terminal coding harness.
 ```
 
-- `web_fetch` - The single web page in markdown format
+- `web_fetch` - The single web page in markdown format. Set `findText` to an array of strings to return snippets from the fetched markdown. Optional `findMode` is `fuzzy` (default, normalized chunk match), `exact` (case-sensitive literal), or `lower` (case-insensitive literal). When smart search is enabled, set `smartQuery` to have a Pi text model answer/extract from the fetched markdown; `findText` and `smartQuery` can be combined.
 - `web_image` - The single image, returned as media content. Respects the Pi image resizing settings:
 
 ![web_image](https://raw.githubusercontent.com/xl0/pi-lovely-web/master/assets/web_image.png)
@@ -55,25 +54,51 @@ The settings are stored in `~/.pi/agent/xl0-pi-lovely-web.json` (global) or `.pi
 
 ```json
 {
-  "webSearch": { "provider": "firecrawl" },
-  "webFetch":  { "provider": "firecrawl" },
-  "webImage":  { "enabled": true },
-  "webApiKeys": {
-    "firecrawl": "fc-...",
-    "exa": "...",
-    "tavily": "...",
-    "brave": "..."
-  }
+  "webSearchProvider": "firecrawl",
+  "webFetchProvider": "firecrawl",
+  "webImageEnabled": true,
+  "smartSearchEnabled": false,
+  "smartSearchModel": "anthropic/claude-sonnet-4-5",
+  "smartSearchMaxTokens": 2000,
+  "smartSearchSystemPrompt": "Process one web_fetch result for a coding agent.\nUse only facts explicitly stated in the provided page text.\n...",
+  "firecrawlApiKey": "fc-...",
+  "exaApiKey": "...",
+  "tavilyApiKey": "...",
+  "braveApiKey": "..."
 }
 ```
 
 API keys can also be set via environment variables: `FIRECRAWL_API_KEY`, `EXA_API_KEY`, `TAVILY_API_KEY`, `BRAVE_API_KEY`.
 
-Search and fetch default to Firecrawl and can use different providers. Set `provider:null`
-on `webSearch` or `webFetch` to remove that tool from Pi's active tool list. Set
-`webImage.enabled:false` to disable `web_image`.
+Search defaults to Firecrawl. Fetch defaults to `disabled`; configure `webFetchProvider` to enable `web_fetch` and `fetchResult:true` first-result fetches from `web_search`. Set `webSearchProvider` or `webFetchProvider` to `disabled` to remove that tool from Pi's active tool list. Set `webImageEnabled:false` to disable `web_image`.
+
+`web_fetch` also supports `findText`, an array of strings to search over fetched markdown. It returns deduped plain-text snippets with 500 characters of context; overlapping contexts are merged, each snippet lists matching queries and counts, UI rendering highlights hits, and returned snippets are capped to about 20k raw characters total. `findMode` defaults to `fuzzy`; `exact` preserves case, `lower` is case-insensitive literal, and `fuzzy` splits text on blank lines, normalizes accents/case/punctuation, scores chunks by query-token coverage plus typo-tolerant token matches, and highlights matched source tokens in the UI.
+
+When `smartSearchEnabled` is true, `smartQuery` post-processes `web_fetch` output with a Pi text model. It supports grounded summaries, extraction, comparisons, troubleshooting, limits/config/API details, security/migration notes, and verbatim code/command/schema examples. The prompt adapts the output format to the query, uses only explicitly stated page facts, preserves exact concrete fields, quotes/source-contexts important claims when useful without repeating the single fetched URL in every evidence bullet, and says `Not found on page.` for absent requested info. `/lovely-web` populates `smartSearchModel` from authenticated Pi text models and defaults to the current model when unset; invalid stored values warn and fall back to the default. `smartSearchSystemPrompt` defaults to the built-in prompt and can be edited. `findText` and `smartQuery` are independent: both read the raw fetched markdown and their outputs are concatenated.
+
+Smart input is limited to half the selected model context estimate. If model context is unknown, the fallback limit is about 60k estimated tokens. If input is trimmed, the tool result includes a visible note with kept/original character counts.
+
+Old `xl0-web-tools.json` configs are migrated to `xl0-pi-lovely-web.json` on load, then deleted.
+
+`web_search` and `web_fetch` parameters are provider-specific and update dynamically when you change providers. Changing providers changes the tool schema and potentially may confuse the model if you change the schema mid-session, but unlikely with modern LLMs.
+
+Search params:
+
+| Provider | Extra `web_search` params |
+|----------|---------------------------|
+| Firecrawl | `source` selects web/news/images; `category` filters to github/research/pdf; `location`/`country` localize; `tbs` applies Google-style time filters. |
+| Exa | `category` narrows Exa's result type; `country` localizes. |
+| Tavily | `topic` selects general/news/finance; `includeImages` returns image URLs; `country` localizes; `timeRange` limits recency. |
+| Brave Search | `source` selects web/news/images; `country` localizes; `searchLang` sets language; `freshness` limits recency. |
+
+Fetch params:
+
+| Provider | Extra `web_fetch` params |
+|----------|--------------------------|
+| Firecrawl | `waitFor` waits before scraping, in ms. |
+| Exa | `maxAgeHours` allows cached page content up to that age. |
+| Tavily | `extractDepth` selects basic or advanced extraction. |
 
-`waitFor` is provider-specific: Firecrawl supports it as an extra pre-capture delay; Exa and Tavily ignore it and `web_fetch` returns a warning if supplied.
 
 `web_image` fetches a direct image URL without provider config/API keys and returns a short text note plus image content to vision-capable models, matching Pi's `read` image behavior. Supported MIME types: PNG, JPEG, WebP, GIF. Defaults to a 5 MB download cap and resizes through Pi's inline image helper before returning content.
 
@@ -85,3 +110,16 @@ on `webSearch` or `webFetch` to remove that tool from Pi's active tool list. Set
 | Exa           | ✓      | ✓     | `x-api-key` |
 | Tavily        | ✓      | ✓     | `Authorization: Bearer` |
 | Brave Search  | ✓      | -     | `X-Subscription-Token` |
+
+## Related projects
+
+|  |  |
+| --- | --- |
+| [Pi Lovely Dev Tools](https://github.com/xl0/pi-lovely-dev-tools) | interactive debugging helpers `/tool` `/show-sysprompt` |
+| [Pi Lovely Codex](https://github.com/xl0/pi-lovely-codex) | GPT fast mode and Codex-style `apply_patch` |
+| [Pi Lovely IDE](https://github.com/xl0/pi-lovely-ide) | IDE integration |
+| [Pi Lovely Config](https://github.com/xl0/pi-lovely-config) | scoped config helpers for Pi extensions |
+
+---
+
+Like this work? [Hire me](https://alexey.work/cv?ref=pi-lovely-web)

package/extensions/lovely-web/command.ts

@@ -1,44 +1,9 @@
-import { homedir } from "node:os"
-import { join, resolve } from "node:path"
-import { type ExtensionAPI, ExtensionInputComponent, getSelectListTheme, getSettingsListTheme } from "@earendil-works/pi-coding-agent"
-import { Container, SelectList, type SettingItem, SettingsList, Text } from "@earendil-works/pi-tui"
-import {
-	applyToolConfig,
-	DEFAULT_PROVIDER_ID,
-	DISABLED_LABEL,
-	getImageMaxSize,
-	isFetchEnabled,
-	isImageEnabled,
-	isImageResizeEnabled,
-	isSearchEnabled,
-	loadConfig,
-	maskApiKey,
-	providerIdFromLabel,
-	providerLabel,
-	providerNames,
-	providers,
-	readConfigFile,
-	writeConfigFile
-} from "./config.js"
-
-function providerSubmenu(title: string, labels: string[], currentValue: string, done: (selectedValue?: string) => void) {
-	const container = new Container()
-	container.addChild(new Text(title, 1, 1))
-	const list = new SelectList(
-		labels.map(label => ({ value: label, label })),
-		Math.min(labels.length, 10),
-		getSelectListTheme()
-	)
-	list.setSelectedIndex(Math.max(0, labels.indexOf(currentValue)))
-	list.onSelect = item => done(item.value)
-	list.onCancel = () => done(undefined)
-	container.addChild(list)
-	return {
-		render: (width: number) => container.render(width),
-		invalidate: () => container.invalidate(),
-		handleInput: (data: string) => list.handleInput(data)
-	}
-}
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent"
+import { ScopedConfigEditor } from "@xl0/pi-lovely-config"
+import { applyToolConfig, loadScopedConfig } from "./config.js"
+import { asErrorMessage } from "./format.js"
+import { resetSmartConfigState, validateSmartConfig } from "./smart.js"
+import { registerLovelyWebSearchTool, registerLovelyWebStaticTools } from "./tools.js"
 
 export function registerLovelyWebCommand(pi: ExtensionAPI) {
 	pi.registerCommand("lovely-web", {
@@ -49,130 +14,34 @@ export function registerLovelyWebCommand(pi: ExtensionAPI) {
 				return
 			}
 
-			const scope = await ctx.ui.select("Config scope:", ["Global (~/.pi/agent/)", "Project (.pi/)"])
-			if (scope === undefined) return
-
-			const configPath = scope.startsWith("Global")
-				? join(homedir(), ".pi", "agent", "xl0-pi-lovely-web.json")
-				: resolve(ctx.cwd, ".pi", "xl0-pi-lovely-web.json")
-
-			const config = readConfigFile(configPath)
-			const save = () => {
-				writeConfigFile(configPath, config)
-				applyToolConfig(pi, loadConfig(ctx.cwd))
-			}
+			try {
+				const config = loadScopedConfig(ctx.cwd, ctx)
+				notifyConfigWarnings(ctx, config.warnings)
 
-			await ctx.ui.custom((_tui, theme, _keybindings, done) => {
-				const searchLabels = [DISABLED_LABEL, ...providerNames.map(id => providers[id]?.label ?? id)]
-				const fetchLabels = [DISABLED_LABEL, ...providerNames.filter(id => providers[id]?.fetch).map(id => providers[id]?.label ?? id)]
-				const items: SettingItem[] = [
-					{
-						id: "search",
-						label: "web_search",
-						currentValue: isSearchEnabled(config) ? providerLabel(config.webSearch?.provider ?? DEFAULT_PROVIDER_ID) : DISABLED_LABEL,
-						description: "Search provider, or disabled to remove web_search from active tools.",
-						submenu: (currentValue, done) => providerSubmenu("Select search provider", searchLabels, currentValue, done)
-					},
-					{
-						id: "fetch",
-						label: "web_fetch",
-						currentValue: isFetchEnabled(config) ? providerLabel(config.webFetch?.provider ?? DEFAULT_PROVIDER_ID) : DISABLED_LABEL,
-						description: "Fetch provider, or disabled to remove web_fetch from active tools.",
-						submenu: (currentValue, done) => providerSubmenu("Select fetch provider", fetchLabels, currentValue, done)
-					},
-					{
-						id: "image",
-						label: "web_image",
-						currentValue: isImageEnabled(config) ? "enabled" : "disabled",
-						description: "Enable or disable direct image URL fetching.",
-						values: ["enabled", "disabled"]
-					},
-					{
-						id: "image-resize",
-						label: "Resize images",
-						currentValue: isImageResizeEnabled(config) ? "on" : "off",
-						description: "Resize fetched images to fit within the max size limit.",
-						values: ["on", "off"]
-					},
-					{
-						id: "image-max-size",
-						label: "Max image size",
-						currentValue: String(getImageMaxSize(config)),
-						description: "Maximum longest side in pixels for resized images.",
-						submenu: (_currentValue: string, done: (selectedValue?: string) => void) =>
-							new ExtensionInputComponent(
-								"Max image size (px):",
-								"Enter size",
-								value => {
-									const n = Number(value)
-									if (!Number.isFinite(n) || n < 1) {
-										done(undefined)
-										return
-									}
-									config.webImage ??= {}
-									config.webImage.maxSize = n
-									save()
-									done(String(n))
-								},
-								() => done(undefined),
-								{ tui: _tui }
-							)
-					},
-					...providerNames.map(id => ({
-						id: `key:${id}`,
-						label: `${providers[id]?.label ?? id} API key`,
-						currentValue: maskApiKey(config.webApiKeys?.[id]),
-						description: `Set API key for ${providers[id]?.label ?? id}.`,
-						submenu: (_currentValue: string, done: (selectedValue?: string) => void) =>
-							new ExtensionInputComponent(
-								`API key for ${providers[id]?.label ?? id}${config.webApiKeys?.[id] ? ` (current: ${maskApiKey(config.webApiKeys[id])})` : ""}:`,
-								"Enter API key",
-								value => {
-									config.webApiKeys ??= {}
-									config.webApiKeys[id] = value
-									save()
-									done(maskApiKey(value))
-								},
-								() => done(undefined),
-								{ tui: _tui }
-							)
-					}))
-				]
-				const container = new Container()
-				container.addChild(new Text(theme.fg("accent", theme.bold("Lovely Web")), 1, 1))
-				const list = new SettingsList(
-					items,
-					Math.min(items.length, 12),
-					getSettingsListTheme(),
-					(id, newValue) => {
-						if (id === "search") {
-							if (newValue === DISABLED_LABEL) config.webSearch = { provider: null }
-							else {
-								const providerId = providerIdFromLabel(newValue)
-								if (providerId) config.webSearch = { provider: providerId }
-							}
-						} else if (id === "fetch") {
-							if (newValue === DISABLED_LABEL) config.webFetch = { provider: null }
-							else {
-								const providerId = providerIdFromLabel(newValue)
-								if (providerId) config.webFetch = { provider: providerId }
-							}
-						} else if (id === "image") {
-							config.webImage = { ...config.webImage, enabled: newValue === "enabled" }
-						} else if (id === "image-resize") {
-							config.webImage = { ...config.webImage, resize: newValue === "on" }
-						}
-						save()
-					},
-					() => done(undefined)
+				await ctx.ui.custom<void>(
+					(tui, theme, _keybindings, done) =>
+						new ScopedConfigEditor({
+							tui,
+							theme,
+							config,
+							onChange(config) {
+								resetSmartConfigState()
+								const value = validateSmartConfig(config.value, ctx) ? config.value : { ...config.value, smartSearchEnabled: false }
+								registerLovelyWebSearchTool(pi, value)
+								registerLovelyWebStaticTools(pi, value)
+								applyToolConfig(pi, value)
+							},
+							done
+						})
 				)
-				container.addChild(list)
-				return {
-					render: (width: number) => container.render(width),
-					invalidate: () => container.invalidate(),
-					handleInput: (data: string) => list.handleInput(data)
-				}
-			})
+			} catch (error) {
+				ctx.ui.notify(asErrorMessage(error), "error")
+			}
 		}
 	})
 }
+
+function notifyConfigWarnings(ctx: ExtensionCommandContext, warnings: ReturnType<typeof loadScopedConfig>["warnings"]): void {
+	if (warnings.length === 0) return
+	ctx.ui.notify(warnings.map(warning => `${warning.path}: ${warning.message}`).join("\n"), "warning")
+}

package/extensions/lovely-web/config.ts

@@ -1,16 +1,24 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
-import { homedir } from "node:os"
-import { join, resolve } from "node:path"
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"
+import { existsSync, readFileSync, rmSync } from "node:fs"
+import { dirname, join } from "node:path"
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent"
+import { type ConfigFromSchema, defineScopedConfig, field, type ScopedConfig } from "@xl0/pi-lovely-config"
 import { braveProvider } from "./providers/brave.js"
 import { exaProvider } from "./providers/exa.js"
 import { firecrawlProvider } from "./providers/firecrawl.js"
 import { tavilyProvider } from "./providers/tavily.js"
-import type { Provider, WebToolsConfig } from "./providers/types.js"
+import type { Provider } from "./providers/types.js"
+import { SMART_SYSTEM_PROMPT } from "./smart.js"
 
-export const DEFAULT_TIMEOUT_MS = 30_000
 export const DEFAULT_PROVIDER_ID = "firecrawl"
-export const DISABLED_LABEL = "Disabled"
+export const CONFIG_FILE_NAME = "xl0-pi-lovely-web.json"
+export const OLD_CONFIG_FILE_NAME = "xl0-web-tools.json"
+export const DISABLED_VALUE = "disabled"
+
+const searchProviderValues = ["firecrawl", "exa", "tavily", "brave"] as const
+const fetchProviderValues = ["firecrawl", "exa", "tavily"] as const
+const searchProviderSettingValues = [DISABLED_VALUE, ...searchProviderValues] as const
+const fetchProviderSettingValues = [DISABLED_VALUE, ...fetchProviderValues] as const
+type SmartModelConfigContext = Pick<ExtensionContext, "model" | "modelRegistry">
 
 export const providers: Record<string, Provider> = {
 	firecrawl: firecrawlProvider,
@@ -19,35 +27,135 @@ export const providers: Record<string, Provider> = {
 	brave: braveProvider
 }
 
-export const providerNames = Object.keys(providers)
+const apiKeyFields = {
+	firecrawl: "firecrawlApiKey",
+	exa: "exaApiKey",
+	tavily: "tavilyApiKey",
+	brave: "braveApiKey"
+} as const
+
+function modelId(model: ExtensionContext["model"]): string | undefined {
+	return model ? `${model.provider}/${model.id}` : undefined
+}
+
+function smartSearchModelField(ctx?: SmartModelConfigContext) {
+	const availableModels = ctx?.modelRegistry.getAvailable().filter(model => model.input.includes("text")) ?? []
+	const [firstModelId, ...otherModelIds] = availableModels.map(model => `${model.provider}/${model.id}`)
+	if (firstModelId === undefined) {
+		return field.string("", {
+			label: "Smart search model",
+			description: "Text model as provider/model. No authenticated text models are currently available.",
+			depth: 1,
+			visibleWhen: ({ get }) => get("smartSearchEnabled") === true
+		})
+	}
+
+	const modelValues = [firstModelId, ...otherModelIds] as [string, ...string[]]
+	const currentModelId = modelId(ctx?.model)
+	const defaultModel = currentModelId && modelValues.includes(currentModelId) ? currentModelId : modelValues[0]
+	const valueDescriptions = Object.fromEntries(availableModels.map(model => [`${model.provider}/${model.id}`, model.name || model.id]))
+	return field.enum(modelValues, defaultModel, {
+		label: "Smart search model",
+		description: "Pi text model for smartQuery post-processing.",
+		search: true,
+		valueDescriptions,
+		depth: 1,
+		visibleWhen: ({ get }) => get("smartSearchEnabled") === true
+	})
+}
+
+function createLovelyWebConfigSchema(ctx?: SmartModelConfigContext) {
+	return {
+		webSearchProvider: field.enum(searchProviderSettingValues, DEFAULT_PROVIDER_ID, {
+			label: "web_search",
+			description: "Search provider, or disabled to remove web_search from active tools."
+		}),
+		webFetchProvider: field.enum(fetchProviderSettingValues, DISABLED_VALUE, {
+			label: "web_fetch",
+			description: "Fetch provider, or disabled to remove web_fetch from active tools."
+		}),
+		webImageEnabled: field.boolean(true, {
+			label: "web_image",
+			description: "Enable or disable direct image URL fetching."
+		}),
+		webImageResize: field.boolean(true, {
+			label: "Resize images",
+			description: "Resize fetched images to fit within the max size limit.",
+			depth: 1,
+			visibleWhen: ({ get }) => get("webImageEnabled") === true
+		}),
+		webImageMaxSize: field.number(2000, {
+			label: "Max image size",
+			description: "Maximum longest side in pixels for resized images.",
+			min: 1,
+			step: 100,
+			depth: 1,
+			visibleWhen: ({ get }) => get("webImageEnabled") === true && get("webImageResize") === true
+		}),
+		smartSearchEnabled: field.boolean(false, {
+			label: "Smart search",
+			description: "Enable smartQuery post-processing for web_fetch."
+		}),
+		smartSearchModel: smartSearchModelField(ctx),
+		smartSearchMaxTokens: field.number(2000, {
+			label: "Smart search max tokens",
+			description: "Maximum output tokens for smartQuery post-processing.",
+			min: 1,
+			step: 100,
+			depth: 1,
+			visibleWhen: ({ get }) => get("smartSearchEnabled") === true
+		}),
+		smartSearchSystemPrompt: field.text(SMART_SYSTEM_PROMPT, {
+			label: "Smart search system prompt",
+			description: "System prompt for smartQuery post-processing. Unset to use the built-in default.",
+			depth: 1,
+			visibleWhen: ({ get }) => get("smartSearchEnabled") === true
+		}),
+		firecrawlApiKey: field.string("", { label: "Firecrawl API key" }),
+		exaApiKey: field.string("", { label: "Exa API key" }),
+		tavilyApiKey: field.string("", { label: "Tavily API key" }),
+		braveApiKey: field.string("", { label: "Brave API key" })
+	} as const
+}
+
+const lovelyWebConfigSchema = createLovelyWebConfigSchema()
+
+export type WebToolsConfig = ConfigFromSchema<typeof lovelyWebConfigSchema>
+
+export const lovelyWebConfigSpec = createLovelyWebConfigSpec()
+
+export function createLovelyWebConfigSpec(ctx?: SmartModelConfigContext): ScopedConfig<WebToolsConfig> {
+	return defineScopedConfig({
+		fileName: CONFIG_FILE_NAME,
+		schema: createLovelyWebConfigSchema(ctx)
+	}) as ScopedConfig<WebToolsConfig>
+}
 
 export function isSearchEnabled(config: WebToolsConfig): boolean {
-	return config.webSearch?.provider !== null
+	return config.webSearchProvider !== DISABLED_VALUE
 }
 
 export function isFetchEnabled(config: WebToolsConfig): boolean {
-	return config.webFetch?.provider !== null
+	return config.webFetchProvider !== DISABLED_VALUE
 }
 
 export function isImageEnabled(config: WebToolsConfig): boolean {
-	return config.webImage?.enabled !== false
+	return config.webImageEnabled
 }
 
 export function isImageResizeEnabled(config: WebToolsConfig): boolean {
-	return config.webImage?.resize !== false
+	return config.webImageResize
 }
 
 export function getImageMaxSize(config: WebToolsConfig): number {
-	return config.webImage?.maxSize ?? 2000
+	return config.webImageMaxSize
 }
 
 function resolveProviderId(type: "search" | "fetch", config: WebToolsConfig): string {
 	if (type === "search" && !isSearchEnabled(config)) throw new Error("web_search is disabled. Enable it via /lovely-web.")
 	if (type === "fetch" && !isFetchEnabled(config)) throw new Error("web_fetch is disabled. Enable it via /lovely-web.")
 
-	const direct = type === "search" ? config.webSearch?.provider : config.webFetch?.provider
-	const fallback = type === "fetch" && isSearchEnabled(config) ? config.webSearch?.provider : undefined
-	const id = direct ?? fallback ?? DEFAULT_PROVIDER_ID
+	const id = type === "search" ? config.webSearchProvider : config.webFetchProvider
 	if (!providers[id]) throw new Error(`Unknown provider "${id}". Available: ${Object.keys(providers).join(", ")}.`)
 	return id
 }
@@ -67,39 +175,22 @@ export function getProvider(type: "search" | "fetch", config: WebToolsConfig): P
 }
 
 export function resolveApiKey(provider: Provider, config: WebToolsConfig): string {
-	const key = config.webApiKeys?.[provider.id]
+	const keyField = apiKeyFields[provider.id as keyof typeof apiKeyFields]
+	const key = keyField ? config[keyField] : undefined
 	if (key) return key
 	const envKey = process.env[provider.envApiKey]
 	if (envKey) return envKey
 	throw new Error(`No API key for ${provider.label}. Set it via /lovely-web or set the ${provider.envApiKey} environment variable.`)
 }
 
-export function loadConfig(cwd: string): WebToolsConfig {
-	const global = readConfigFile(join(homedir(), ".pi", "agent", "xl0-pi-lovely-web.json"))
-	const project = readConfigFile(resolve(cwd, ".pi", "xl0-pi-lovely-web.json"))
-	return {
-		...global,
-		...project,
-		webSearch: { provider: DEFAULT_PROVIDER_ID, ...global.webSearch, ...project.webSearch },
-		webFetch: { provider: DEFAULT_PROVIDER_ID, ...global.webFetch, ...project.webFetch },
-		webImage: { ...global.webImage, ...project.webImage },
-		webApiKeys: { ...global.webApiKeys, ...project.webApiKeys }
-	}
-}
-
-export function readConfigFile(path: string): WebToolsConfig {
-	try {
-		if (!existsSync(path)) return {}
-		const raw = readFileSync(path, "utf-8")
-		return JSON.parse(raw) as WebToolsConfig
-	} catch {
-		return {}
-	}
+export function loadConfig(cwd: string, ctx?: SmartModelConfigContext): WebToolsConfig {
+	return loadScopedConfig(cwd, ctx).value
 }
 
-export function writeConfigFile(path: string, config: WebToolsConfig): void {
-	mkdirSync(resolve(path, ".."), { recursive: true })
-	writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`, "utf-8")
+export function loadScopedConfig(cwd: string, ctx?: SmartModelConfigContext): ScopedConfig<WebToolsConfig> {
+	const config = createLovelyWebConfigSpec(ctx).load(cwd)
+	migrateOldConfig(config)
+	return config
 }
 
 export function applyToolConfig(pi: ExtensionAPI, config: WebToolsConfig): void {
@@ -113,19 +204,50 @@ export function applyToolConfig(pi: ExtensionAPI, config: WebToolsConfig): void
 	pi.setActiveTools([...active])
 }
 
-export function providerLabel(id: string | undefined): string {
-	return id ? (providers[id]?.label ?? id) : "(not set)"
-}
-
-export function providerIdFromLabel(label: string): string | undefined {
-	return providerNames.find(id => providers[id]?.label === label)
-}
-
-export function maskApiKey(key: string | undefined): string {
-	if (!key) return "(not set)"
-	const maskLength = Math.max(5, key.length - 8)
-	const visible = Math.max(0, key.length - maskLength)
-	const startLength = Math.min(4, Math.ceil(visible / 2))
-	const endLength = Math.min(4, visible - startLength)
-	return `${key.slice(0, startLength)}${"*".repeat(maskLength)}${endLength > 0 ? key.slice(-endLength) : ""}`
+type OldConfig = {
+	webSearch?: { provider?: string | null }
+	webFetch?: { provider?: string | null }
+	webImage?: { enabled?: boolean; resize?: boolean; maxSize?: number }
+	webApiKeys?: Record<string, string>
+}
+
+function migrateOldConfig(config: ScopedConfig<WebToolsConfig>): void {
+	for (const scope of config.scopes) {
+		const newPath = config.path(scope)
+		const oldPath = join(dirname(newPath), OLD_CONFIG_FILE_NAME)
+		if (!existsSync(oldPath)) continue
+
+		try {
+			const old = JSON.parse(readFileSync(oldPath, "utf-8")) as OldConfig
+			if (!old || typeof old !== "object" || Array.isArray(old)) throw new Error("old config must be an object")
+			const update = <Key extends keyof WebToolsConfig & string>(key: Key, value: WebToolsConfig[Key]) => {
+				if (config.scoped[scope][key] === undefined) config.update(scope, key, value)
+			}
+
+			const searchProvider = old.webSearch?.provider
+			if (searchProvider === null) update("webSearchProvider", DISABLED_VALUE)
+			else if (typeof searchProvider === "string" && (searchProviderSettingValues as readonly string[]).includes(searchProvider)) {
+				update("webSearchProvider", searchProvider as WebToolsConfig["webSearchProvider"])
+			}
+
+			const fetchProvider = old.webFetch?.provider
+			if (fetchProvider === null) update("webFetchProvider", DISABLED_VALUE)
+			else if (typeof fetchProvider === "string" && (fetchProviderSettingValues as readonly string[]).includes(fetchProvider)) {
+				update("webFetchProvider", fetchProvider as WebToolsConfig["webFetchProvider"])
+			}
+
+			if (typeof old.webImage?.enabled === "boolean") update("webImageEnabled", old.webImage.enabled)
+			if (typeof old.webImage?.resize === "boolean") update("webImageResize", old.webImage.resize)
+			if (typeof old.webImage?.maxSize === "number" && old.webImage.maxSize >= 1) update("webImageMaxSize", old.webImage.maxSize)
+
+			for (const [providerId, key] of Object.entries(old.webApiKeys ?? {})) {
+				const keyField = apiKeyFields[providerId as keyof typeof apiKeyFields]
+				if (keyField && typeof key === "string") update(keyField, key)
+			}
+		} catch {
+			// Best-effort legacy migration: malformed/stale old config should not block startup.
+		} finally {
+			rmSync(oldPath, { force: true })
+		}
+	}
 }

package/extensions/lovely-web/constants.ts

@@ -0,0 +1 @@
+export const DEFAULT_TIMEOUT_MS = 30_000