@demigodmode/pi-web-agent 0.6.0 → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,207 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is intentionally simple and release-oriented.
+
+## Unreleased
+
+### Added
+- Nothing yet.
+
+### Changed
+- Nothing yet.
+
+### Fixed
+- Nothing yet.
+
+### Breaking
+- None.
+
+## [1.1.0] - 2026-05-25
+### Added
+- Added explicit opt-in fallback from SearXNG to DuckDuckGo and Firecrawl to HTTP.
+- Added supported SearXNG and Firecrawl backend options in config.
+- Added env-gated live tests for local SearXNG and Firecrawl instances.
+
+### Changed
+- `/web-agent show` and `/web-agent doctor` now report configured backend fallback/options.
+
+### Fixed
+- Nothing yet.
+
+### Breaking
+- None.
+
+## [1.0.0] - 2026-05-08
+### Added
+- Added one-time `pi-web-agent` changelog notices after package updates and `/web-agent changelog` for manual viewing.
+
+### Changed
+- Migrated Pi package imports to `@earendil-works/*` after the upstream Pi scope move.
+
+### Fixed
+- Nothing yet.
+
+### Breaking
+- This release requires Pi 0.74+. Users on older Pi versions should stay on `@demigodmode/pi-web-agent@0.6.x` until they update Pi.
+
+## [0.6.0] - 2026-05-04
+### Added
+- Added configurable web backends for `web_explore`, including SearXNG search and Firecrawl fetch support.
+- Added backend diagnostics to `/web-agent doctor`, including config validation and self-hosted endpoint checks.
+- Added dedicated self-hosted backend docs for connecting existing SearXNG and Firecrawl services.
+
+### Changed
+- `/web-agent show` now includes the effective backend configuration.
+- `web_explore` now loads the effective backend config while preserving the default DuckDuckGo, HTTP, and local-browser behavior.
+
+### Fixed
+- Fixed backend config merging so provider-specific fields do not leak when a higher-precedence config changes providers.
+- Kept the configured `web_explore` workflow reusable while backend config is unchanged, avoiding unnecessary backend/cache recreation.
+
+### Breaking
+- None.
+
+## [0.5.1] - 2026-05-04
+### Added
+- Nothing yet.
+
+### Changed
+- Nothing yet.
+
+### Fixed
+- Fixed the Windows browser-resolution test so it is deterministic on Linux CI.
+
+### Breaking
+- None.
+
+## [0.5.0] - 2026-05-04
+### Added
+- Added `/web-agent doctor` to report extension, runtime dependency, and browser detection status.
+- Added a `/web-agent` action menu for settings, config display, doctor, and reset actions.
+
+### Changed
+- Migrated runtime schema imports from `@sinclair/typebox` to `typebox` for Pi 0.69 compatibility.
+- Documented the current headless rendering browser requirement and doctor command.
+
+### Fixed
+- Fixed headless browser detection so Chrome, Chromium, Edge, and Brave can be found across Windows, macOS, and Linux instead of only checking Windows Chrome/Edge paths.
+
+### Breaking
+- None.
+
+## [0.4.0] - 2026-04-29
+### Added
+- Made `web_explore` the single public web research tool, with search, fetch, source ranking, and headless escalation handled internally.
+- Added adaptive research helpers for query planning, candidate selection, evidence ranking, stop decisions, and answer synthesis.
+- Added preview/verbose provenance for `web_explore` showing which internal reader produced each finding.
+
+### Changed
+- Simplified `/web-agent` presentation settings to `defaultMode` and `web_explore` only.
+- Updated live web evals to treat shell/network fallbacks after `web_explore` as a quality issue.
+- Updated the release script to use `npm version --no-git-tag-version` before tagging so package metadata is changed through npm instead of regex replacement.
+
+### Fixed
+- Turned successful headless reads into usable `web_explore` evidence instead of returning empty results for dynamic docs pages.
+- Filtered headless bot-check/security-verification pages out of research evidence.
+- Made empty research results display as “No usable evidence found” instead of looking like a successful synthesis.
+- Added the Linux Rollup optional package to the lockfile so GitHub Actions can build from `npm ci` without patch-installing Rollup.
+
+### Breaking
+- None.
+
+## [0.3.1] - 2026-04-22
+### Added
+- Nothing yet.
+
+### Changed
+- Stopped self-upgrading npm inside the publish workflow before install and publish steps.
+- Added GitHub release creation to the tag publish workflow.
+
+### Fixed
+- Fixed the tag publish workflow so npm publishing no longer fails before `npm ci`.
+
+### Breaking
+- None.
+
+## [0.3.0] - 2026-04-22
+### Added
+- Added compact, preview, and verbose presentation modes for web tool output.
+- Added a user-facing `/web-agent` settings UI plus helper commands for showing, resetting, and changing presentation config.
+- Added global and project-local presentation config files with project-overrides-global precedence.
+- Added docs for presentation settings, config paths, and command usage.
+
+### Changed
+- Made compact output the default presentation mode for all web tools.
+- Made bare `/web-agent` open the settings UI directly.
+
+### Fixed
+- Fixed settings scope switching so global and project drafts do not leak into each other.
+- Fixed config persistence so inherited values are not unnecessarily written into lower-precedence config files.
+- Fixed command notifications to use supported Pi UI notify levels.
+
+### Breaking
+- None.
+
+## [0.2.2] - 2026-04-21
+### Added
+- Expanded the live web eval so it covers deterministic search failure cases and reports when follow-up web calls were blocked after `web_explore`.
+
+### Changed
+- Tightened post-`web_explore` discipline by blocking same-flow low-level web tool churn instead of relying on prompt wording alone.
+
+### Fixed
+- Split `web_search` failures into more useful states like no results, parse failures, blocked pages, and fetch failures.
+- Catch DuckDuckGo challenge pages that still return HTTP 200 so blocked searches stop looking like vague parser bugs.
+- Stopped the model from spiraling into extra `web_search` / `web_fetch` calls after a successful `web_explore` in the live-eval cases.
+
+### Breaking
+- None.
+
+## [0.2.1] - 2026-04-20
+### Added
+- Nothing yet.
+
+### Changed
+- Nothing yet.
+
+### Fixed
+- Added the missing npm `--provenance` flag to the publish workflow so Trusted Publishing can exchange the GitHub OIDC token correctly.
+
+### Breaking
+- None.
+
+## [0.2.0] - 2026-04-20
+### Added
+- Added AGPL licensing, a release foundation test, and changelog-driven release tooling.
+- Added GitHub Actions workflows for CI and tag-based npm publishing.
+- Added maintainer docs for releases, self-hosted runners, and main branch protection.
+
+### Changed
+- Documented the release process in the README.
+- Switched npm publishing guidance from `NPM_TOKEN` secrets to npm Trusted Publishing.
+
+### Fixed
+- Stopped injecting post-`web_explore` reminder text through a context hook so it no longer leaks into normal sessions.
+- Worked around Rollup's missing Linux native package in GitHub Actions so CI and publish jobs run reliably on Ubuntu.
+
+### Breaking
+- None.
+
+## [0.1.0] - 2026-04-20
+
+### Added
+- Published `@demigodmode/pi-web-agent` as a Pi package.
+- Added explicit web research tools for search, HTTP fetch, headless fetch, and bounded exploration.
+- Added headless fetch implementation and package install validation.
+
+### Changed
+- Tightened follow-up tool discipline after `web_explore`.
+- Split package build output from repo-local development tooling.
+
+### Fixed
+- Fixed post-`web_explore` reminder handling so it is derived from context instead of shared mutable state.
+
+### Breaking
+- None.

package/README.md

@@ -14,6 +14,8 @@ That sounds obvious, but a lot of agent tooling gets fuzzy right there. This pac
 
 ## Install
 
+Compatibility notice: current `pi-web-agent` requires Pi 0.74+ because Pi packages moved to the `@earendil-works/*` scope. Update Pi before updating this package. If you are on an older Pi version, stay on `@demigodmode/pi-web-agent@0.6.x` until Pi is updated.
+
 ```bash
 pi install npm:@demigodmode/pi-web-agent
 ```
@@ -71,6 +73,7 @@ Helper commands:
 ```text
 /web-agent doctor
 /web-agent show
+/web-agent changelog
 /web-agent reset project
 /web-agent reset global
 /web-agent mode preview
@@ -106,33 +109,9 @@ Example:
 }
 ```
 
-Backend config is also supported. Defaults are DuckDuckGo search, plain HTTP fetch, and local browser headless fallback:
-
-```json
-{
-  "backends": {
-    "search": { "provider": "duckduckgo" },
-    "fetch": { "provider": "http" },
-    "headless": { "provider": "local-browser" }
-  }
-}
-```
-
-Self-hosted example for existing SearXNG/Firecrawl services:
-
-```json
-{
-  "backends": {
-    "search": { "provider": "searxng", "baseUrl": "http://localhost:8080" },
-    "fetch": { "provider": "firecrawl", "baseUrl": "http://localhost:3002" },
-    "headless": { "provider": "local-browser" }
-  }
-}
-```
-
-Prefer `PI_WEB_AGENT_FIRECRAWL_API_KEY` for Firecrawl auth instead of putting secrets in project config. `/web-agent doctor` validates required backend fields and checks configured self-hosted endpoints.
+Backend config is also supported. Defaults remain DuckDuckGo search, plain HTTP fetch, and local browser headless fallback. If you already run SearXNG or Firecrawl, see the self-hosted backend guide:
 
-Full guide: https://demigodmode.github.io/pi-web-agent/self-hosted-backends
+- https://demigodmode.github.io/pi-web-agent/self-hosted-backends
 
 ## Local development
 

package/dist/backends/config.d.ts

@@ -1,11 +1,24 @@
+export type SearxngOptions = {
+    categories?: string[];
+    language?: string;
+    safesearch?: 0 | 1 | 2;
+};
+export type FirecrawlOptions = {
+    formats?: string[];
+    onlyMainContent?: boolean;
+};
 export type SearchBackendConfig = {
     provider: 'duckduckgo' | 'searxng';
     baseUrl?: string;
+    fallback?: 'duckduckgo';
+    options?: SearxngOptions;
 };
 export type FetchBackendConfig = {
     provider: 'http' | 'firecrawl';
     baseUrl?: string;
     apiKey?: string;
+    fallback?: 'http';
+    options?: FirecrawlOptions;
 };
 export type HeadlessBackendConfig = {
     provider: 'local-browser';
@@ -25,11 +38,15 @@ export type BackendConfigFile = {
         search?: {
             provider?: unknown;
             baseUrl?: unknown;
+            fallback?: unknown;
+            options?: unknown;
         };
         fetch?: {
             provider?: unknown;
             baseUrl?: unknown;
             apiKey?: unknown;
+            fallback?: unknown;
+            options?: unknown;
         };
         headless?: {
             provider?: unknown;

package/dist/backends/config.js

@@ -3,6 +3,38 @@ export const DEFAULT_BACKEND_CONFIG = {
     fetch: { provider: 'http' },
     headless: { provider: 'local-browser' }
 };
+function extractStringArray(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const strings = value.filter((item) => typeof item === 'string');
+    return strings.length === value.length ? strings : undefined;
+}
+function extractSearxngOptions(value) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const raw = value;
+    const options = {};
+    const categories = extractStringArray(raw.categories);
+    if (categories)
+        options.categories = categories;
+    if (typeof raw.language === 'string')
+        options.language = raw.language;
+    if (raw.safesearch === 0 || raw.safesearch === 1 || raw.safesearch === 2)
+        options.safesearch = raw.safesearch;
+    return Object.keys(options).length > 0 ? options : undefined;
+}
+function extractFirecrawlOptions(value) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const raw = value;
+    const options = {};
+    const formats = extractStringArray(raw.formats);
+    if (formats)
+        options.formats = formats;
+    if (typeof raw.onlyMainContent === 'boolean')
+        options.onlyMainContent = raw.onlyMainContent;
+    return Object.keys(options).length > 0 ? options : undefined;
+}
 export function extractBackendConfigOverride(file) {
     const backends = file?.backends;
     const override = {};
@@ -11,6 +43,13 @@ export function extractBackendConfigOverride(file) {
         if (typeof backends.search.baseUrl === 'string') {
             override.search.baseUrl = backends.search.baseUrl;
         }
+        if (backends.search.fallback === 'duckduckgo') {
+            override.search.fallback = 'duckduckgo';
+        }
+        const options = extractSearxngOptions(backends.search.options);
+        if (options) {
+            override.search.options = options;
+        }
     }
     if (backends?.fetch?.provider === 'http' || backends?.fetch?.provider === 'firecrawl') {
         override.fetch = { provider: backends.fetch.provider };
@@ -20,6 +59,13 @@ export function extractBackendConfigOverride(file) {
         if (typeof backends.fetch.apiKey === 'string') {
             override.fetch.apiKey = backends.fetch.apiKey;
         }
+        if (backends.fetch.fallback === 'http') {
+            override.fetch.fallback = 'http';
+        }
+        const options = extractFirecrawlOptions(backends.fetch.options);
+        if (options) {
+            override.fetch.options = options;
+        }
     }
     if (backends?.headless?.provider === 'local-browser') {
         override.headless = { provider: 'local-browser' };
@@ -34,6 +80,25 @@ export function validateBackendConfig(config) {
     if (config.fetch.provider === 'firecrawl' && !config.fetch.baseUrl) {
         issues.push('fetch provider firecrawl requires backends.fetch.baseUrl');
     }
+    if (config.search.fallback === 'duckduckgo' && config.search.provider !== 'searxng') {
+        issues.push('search fallback duckduckgo is only supported when search provider is searxng');
+    }
+    if (config.fetch.fallback === 'http' && config.fetch.provider !== 'firecrawl') {
+        issues.push('fetch fallback http is only supported when fetch provider is firecrawl');
+    }
+    if (config.search.options?.categories && config.search.options.categories.length === 0) {
+        issues.push('search options.categories must contain at least one category when provided');
+    }
+    if (config.search.options?.language !== undefined && !config.search.options.language.trim()) {
+        issues.push('search options.language must not be empty when provided');
+    }
+    if (config.search.options?.safesearch !== undefined &&
+        ![0, 1, 2].includes(config.search.options.safesearch)) {
+        issues.push('search options.safesearch must be 0, 1, or 2 when provided');
+    }
+    if (config.fetch.options?.formats && config.fetch.options.formats.length === 0) {
+        issues.push('fetch options.formats must contain at least one format when provided');
+    }
     return issues;
 }
 function mergeSearchConfig(current, override) {

package/dist/backends/doctor.js

@@ -6,12 +6,25 @@ function withTimeout(timeoutMs) {
 function message(error) {
     return error instanceof Error ? error.message : String(error);
 }
-function searxngDoctorUrl(baseUrl) {
+function searxngDoctorUrl(baseUrl, options = {}) {
     const url = new URL('/search', baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`);
     url.searchParams.set('q', 'pi-web-agent-doctor');
     url.searchParams.set('format', 'json');
+    if (options.categories?.length)
+        url.searchParams.set('categories', options.categories.join(','));
+    if (options.language)
+        url.searchParams.set('language', options.language);
+    if (options.safesearch !== undefined)
+        url.searchParams.set('safesearch', String(options.safesearch));
     return url.toString();
 }
+function firecrawlDoctorBody(options = {}) {
+    return {
+        url: 'https://example.com',
+        formats: options.formats ?? ['markdown'],
+        ...(options.onlyMainContent !== undefined ? { onlyMainContent: options.onlyMainContent } : {})
+    };
+}
 export async function checkBackendHealth(config, { fetchImpl = fetch, timeoutMs = 3_000 } = {}) {
     const lines = [];
     if (config.search.provider === 'duckduckgo') {
@@ -23,7 +36,7 @@ export async function checkBackendHealth(config, { fetchImpl = fetch, timeoutMs
     else {
         const timeout = withTimeout(timeoutMs);
         try {
-            const response = await fetchImpl(searxngDoctorUrl(config.search.baseUrl), { signal: timeout.signal });
+            const response = await fetchImpl(searxngDoctorUrl(config.search.baseUrl, config.search.options), { signal: timeout.signal });
             const json = (await response.json());
             lines.push(response.ok && Array.isArray(json.results)
                 ? 'search backend: searxng ok'
@@ -36,6 +49,9 @@ export async function checkBackendHealth(config, { fetchImpl = fetch, timeoutMs
             timeout.done();
         }
     }
+    if (config.search.fallback) {
+        lines.push(`search fallback: ${config.search.fallback}`);
+    }
     if (config.fetch.provider === 'http') {
         lines.push('fetch backend: http');
     }
@@ -52,7 +68,7 @@ export async function checkBackendHealth(config, { fetchImpl = fetch, timeoutMs
             const response = await fetchImpl(new URL('/v1/scrape', config.fetch.baseUrl).toString(), {
                 method: 'POST',
                 headers,
-                body: JSON.stringify({ url: 'https://example.com', formats: ['markdown'] }),
+                body: JSON.stringify(firecrawlDoctorBody(config.fetch.options)),
                 signal: timeout.signal
             });
             lines.push(response.ok ? 'fetch backend: firecrawl ok' : `fetch backend: firecrawl warning (HTTP ${response.status})`);
@@ -64,5 +80,8 @@ export async function checkBackendHealth(config, { fetchImpl = fetch, timeoutMs
             timeout.done();
         }
     }
+    if (config.fetch.fallback) {
+        lines.push(`fetch fallback: ${config.fetch.fallback}`);
+    }
     return lines;
 }

package/dist/backends/factory.d.ts

@@ -1,3 +1,8 @@
+import { createFirecrawlFetcher } from '../fetch/firecrawl-fetch.js';
+import { createSearxngSearchTool } from '../search/searxng.js';
+import { createWebFetchHeadlessTool } from '../tools/web-fetch-headless.js';
+import { createWebFetchTool } from '../tools/web-fetch.js';
+import { createWebSearchTool } from '../tools/web-search.js';
 import type { WebFetchHeadlessResponse, WebFetchResponse, WebSearchResponse } from '../types.js';
 import { type BackendConfig } from './config.js';
 export type BackendSet = {
@@ -11,4 +16,11 @@ export type BackendSet = {
         url: string;
     }) => Promise<WebFetchHeadlessResponse>;
 };
-export declare function createBackendSet(config?: BackendConfig): BackendSet;
+export type BackendFactoryDeps = {
+    createDuckDuckGoSearch?: typeof createWebSearchTool;
+    createSearxngSearch?: typeof createSearxngSearchTool;
+    createHttpFetch?: typeof createWebFetchTool;
+    createFirecrawlFetch?: typeof createFirecrawlFetcher;
+    createHeadlessFetch?: typeof createWebFetchHeadlessTool;
+};
+export declare function createBackendSet(config?: BackendConfig, deps?: BackendFactoryDeps): BackendSet;

package/dist/backends/factory.js

@@ -34,25 +34,72 @@ function invalidFirecrawlFetch() {
         return { ...result, presentation: buildFetchPresentation(result) };
     };
 }
-export function createBackendSet(config = DEFAULT_BACKEND_CONFIG) {
-    const search = config.search.provider === 'searxng'
+function withSearchFallback(primary, fallback) {
+    return async (input) => {
+        const first = await primary(input);
+        if (first.status !== 'error')
+            return first;
+        const second = await fallback(input);
+        const result = {
+            ...second,
+            metadata: {
+                ...second.metadata,
+                fallbackFrom: 'searxng',
+                fallbackReason: first.error?.message ?? 'SearXNG search failed.'
+            }
+        };
+        return { ...result, presentation: buildSearchPresentation(result) };
+    };
+}
+function withFetchFallback(primary, fallback) {
+    return async (input) => {
+        const first = await primary(input);
+        if (first.status !== 'error' && first.status !== 'needs_headless')
+            return first;
+        const second = await fallback(input);
+        const result = {
+            ...second,
+            metadata: {
+                ...second.metadata,
+                fallbackFrom: 'firecrawl',
+                fallbackReason: first.error?.message ?? 'Firecrawl fetch failed.'
+            }
+        };
+        return { ...result, presentation: buildFetchPresentation(result) };
+    };
+}
+export function createBackendSet(config = DEFAULT_BACKEND_CONFIG, deps = {}) {
+    const createDuckDuckGoSearch = deps.createDuckDuckGoSearch ?? createWebSearchTool;
+    const createSearxngSearch = deps.createSearxngSearch ?? createSearxngSearchTool;
+    const createHttpFetch = deps.createHttpFetch ?? createWebFetchTool;
+    const createFirecrawlFetch = deps.createFirecrawlFetch ?? createFirecrawlFetcher;
+    const createHeadlessFetch = deps.createHeadlessFetch ?? createWebFetchHeadlessTool;
+    let search = config.search.provider === 'searxng'
         ? config.search.baseUrl
-            ? createSearxngSearchTool({ baseUrl: config.search.baseUrl })
+            ? createSearxngSearch({ baseUrl: config.search.baseUrl, options: config.search.options })
             : invalidSearxngSearch()
-        : createWebSearchTool();
-    const fetchPage = config.fetch.provider === 'firecrawl'
+        : createDuckDuckGoSearch();
+    if (config.search.provider === 'searxng' && config.search.fallback === 'duckduckgo') {
+        search = withSearchFallback(search, createDuckDuckGoSearch());
+    }
+    const httpFetch = createHttpFetch();
+    let fetchPage = config.fetch.provider === 'firecrawl'
         ? config.fetch.baseUrl
-            ? createWebFetchTool({
-                fetchPage: createFirecrawlFetcher({
+            ? createHttpFetch({
+                fetchPage: createFirecrawlFetch({
                     baseUrl: config.fetch.baseUrl,
-                    apiKey: config.fetch.apiKey ?? process.env.PI_WEB_AGENT_FIRECRAWL_API_KEY
+                    apiKey: config.fetch.apiKey ?? process.env.PI_WEB_AGENT_FIRECRAWL_API_KEY,
+                    options: config.fetch.options
                 })
             })
-            : createWebFetchTool({ fetchPage: invalidFirecrawlFetch() })
-        : createWebFetchTool();
+            : createHttpFetch({ fetchPage: invalidFirecrawlFetch() })
+        : httpFetch;
+    if (config.fetch.provider === 'firecrawl' && config.fetch.fallback === 'http') {
+        fetchPage = withFetchFallback(fetchPage, httpFetch);
+    }
     return {
         search,
         fetchPage,
-        headlessFetch: createWebFetchHeadlessTool()
+        headlessFetch: createHeadlessFetch()
     };
 }

package/dist/changelog-notice.d.ts

@@ -0,0 +1,16 @@
+export type ChangelogEntry = {
+    version: string;
+    content: string;
+};
+type ChangelogOptions = {
+    packageRoot?: string;
+    statePath?: string;
+};
+export declare function parseChangelogEntries(changelog: string): ChangelogEntry[];
+export declare function markChangelogSeen({ statePath, version }: {
+    statePath?: string;
+    version: string;
+}): Promise<void>;
+export declare function getUpdateChangelogNotice(options?: ChangelogOptions): Promise<string | undefined>;
+export declare function getLatestChangelogEntry(options?: ChangelogOptions): Promise<string | undefined>;
+export {};

package/dist/changelog-notice.js

@@ -0,0 +1,105 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+export function parseChangelogEntries(changelog) {
+    const lines = changelog.split(/\r?\n/);
+    const entries = [];
+    let currentVersion;
+    let currentLines = [];
+    function flush() {
+        if (currentVersion && currentLines.length > 0) {
+            entries.push({ version: currentVersion, content: currentLines.join('\n').trim() });
+        }
+    }
+    for (const line of lines) {
+        if (line.startsWith('## ')) {
+            flush();
+            const match = line.match(/^##\s+\[?(\d+\.\d+\.\d+)\]?/);
+            currentVersion = match?.[1];
+            currentLines = currentVersion ? [line] : [];
+            continue;
+        }
+        if (currentVersion) {
+            currentLines.push(line);
+        }
+    }
+    flush();
+    return entries;
+}
+function compareVersions(left, right) {
+    const leftParts = left.split('.').map(Number);
+    const rightParts = right.split('.').map(Number);
+    for (let i = 0; i < 3; i += 1) {
+        const diff = (leftParts[i] || 0) - (rightParts[i] || 0);
+        if (diff !== 0)
+            return diff;
+    }
+    return 0;
+}
+function defaultPackageRoot() {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    return path.basename(here) === 'dist' ? path.dirname(here) : path.dirname(here);
+}
+function defaultStatePath() {
+    const homeDir = process.env.USERPROFILE ?? process.env.HOME ?? '';
+    return path.join(homeDir, '.pi', 'agent', 'extensions', 'pi-web-agent', 'state.json');
+}
+async function readPackageVersion(packageRoot) {
+    try {
+        const raw = await readFile(path.join(packageRoot, 'package.json'), 'utf8');
+        const parsed = JSON.parse(raw);
+        return typeof parsed.version === 'string' ? parsed.version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function readChangelogEntries(packageRoot) {
+    try {
+        return parseChangelogEntries(await readFile(path.join(packageRoot, 'CHANGELOG.md'), 'utf8'));
+    }
+    catch {
+        return [];
+    }
+}
+async function readState(statePath) {
+    try {
+        return JSON.parse(await readFile(statePath, 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+export async function markChangelogSeen({ statePath = defaultStatePath(), version }) {
+    try {
+        await mkdir(path.dirname(statePath), { recursive: true });
+        await writeFile(statePath, `${JSON.stringify({ lastChangelogVersion: version }, null, 2)}\n`, 'utf8');
+    }
+    catch {
+        // Changelog display is best effort. Never block extension startup on state persistence.
+    }
+}
+export async function getUpdateChangelogNotice(options = {}) {
+    const packageRoot = options.packageRoot ?? defaultPackageRoot();
+    const statePath = options.statePath ?? defaultStatePath();
+    const version = await readPackageVersion(packageRoot);
+    if (!version)
+        return undefined;
+    const state = await readState(statePath);
+    if (!state.lastChangelogVersion) {
+        await markChangelogSeen({ statePath, version });
+        return undefined;
+    }
+    if (compareVersions(version, state.lastChangelogVersion) <= 0) {
+        return undefined;
+    }
+    const entries = (await readChangelogEntries(packageRoot))
+        .filter((entry) => compareVersions(entry.version, state.lastChangelogVersion || '0.0.0') > 0)
+        .map((entry) => entry.content);
+    await markChangelogSeen({ statePath, version });
+    return entries.length > 0 ? entries.join('\n\n') : undefined;
+}
+export async function getLatestChangelogEntry(options = {}) {
+    const entries = await readChangelogEntries(options.packageRoot ?? defaultPackageRoot());
+    return entries[0]?.content;
+}

package/dist/commands/web-agent-config.d.ts

@@ -1,5 +1,5 @@
 import { type BackendConfig } from '../backends/config.js';
-import { type ExtensionAPI } from '@mariozechner/pi-coding-agent';
+import { type ExtensionAPI } from '@earendil-works/pi-coding-agent';
 import { loadPresentationConfigLayers, type LoadedPresentationConfig } from '../presentation/config-store.js';
 import { type BrowserResolutionResult } from '../fetch/browser-resolution.js';
 import type { PresentationConfig, PresentationConfigOverride, PresentationScope } from '../presentation/types.js';
@@ -15,6 +15,7 @@ type CommandDeps = {
     };
     checkTypebox?: () => Promise<boolean>;
     checkBackends?: (config: BackendConfig) => Promise<string[]>;
+    getChangelog?: () => Promise<string | undefined>;
 };
 export type SettingsDraftState = {
     scope: PresentationScope;

package/dist/commands/web-agent-config.js

@@ -1,10 +1,11 @@
 import { DEFAULT_BACKEND_CONFIG, validateBackendConfig } from '../backends/config.js';
 import { checkBackendHealth } from '../backends/doctor.js';
-import { DynamicBorder, getSettingsListTheme } from '@mariozechner/pi-coding-agent';
-import { Container, SelectList, SettingsList, Text } from '@mariozechner/pi-tui';
+import { DynamicBorder, getSettingsListTheme } from '@earendil-works/pi-coding-agent';
+import { Container, SelectList, SettingsList, Text } from '@earendil-works/pi-tui';
 import { DEFAULT_PRESENTATION_CONFIG, mergePresentationConfigLayers, resolvePresentationMode } from '../presentation/config.js';
 import { loadPresentationConfigLayers, resetPresentationConfigScope, savePresentationConfigScope } from '../presentation/config-store.js';
 import { resolveBrowserExecutable } from '../fetch/browser-resolution.js';
+import { getLatestChangelogEntry } from '../changelog-notice.js';
 const PRESENTATION_TOOL_NAMES = ['web_explore'];
 function parseScopeToken(token) {
     return token === 'global' || token === 'project' ? token : undefined;
@@ -24,16 +25,33 @@ async function defaultCheckTypebox() {
         return false;
     }
 }
+function formatSearchOptions(config) {
+    return [
+        config.fallback ? `fallback ${config.fallback}` : undefined,
+        config.options?.categories?.length ? `categories ${config.options.categories.join(',')}` : undefined,
+        config.options?.language ? `language ${config.options.language}` : undefined,
+        config.options?.safesearch !== undefined ? `safesearch ${config.options.safesearch}` : undefined
+    ].filter(Boolean).join(' ');
+}
+function formatFetchOptions(config) {
+    return [
+        config.fallback ? `fallback ${config.fallback}` : undefined,
+        config.options?.formats?.length ? `formats ${config.options.formats.join(',')}` : undefined,
+        config.options?.onlyMainContent !== undefined ? `onlyMainContent ${config.options.onlyMainContent}` : undefined
+    ].filter(Boolean).join(' ');
+}
 function formatBackendSummary(config = DEFAULT_BACKEND_CONFIG) {
-    const search = config.search.baseUrl
+    const searchSuffix = formatSearchOptions(config.search);
+    const fetchSuffix = formatFetchOptions(config.fetch);
+    const searchBase = config.search.baseUrl
         ? `search: ${config.search.provider} (${config.search.baseUrl})`
         : `search: ${config.search.provider}`;
-    const fetch = config.fetch.baseUrl
+    const fetchBase = config.fetch.baseUrl
         ? `fetch: ${config.fetch.provider} (${config.fetch.baseUrl})`
         : `fetch: ${config.fetch.provider}`;
     return [
-        search,
-        fetch,
+        searchSuffix ? `${searchBase} ${searchSuffix}` : searchBase,
+        fetchSuffix ? `${fetchBase} ${fetchSuffix}` : fetchBase,
         `headless: ${config.headless.provider}`
     ].join('\n');
 }
@@ -249,6 +267,7 @@ export function registerWebAgentConfigCommands(pi, deps = {}) {
     };
     const checkTypebox = deps.checkTypebox ?? defaultCheckTypebox;
     const checkBackends = deps.checkBackends ?? ((config) => checkBackendHealth(config));
+    const getChangelog = deps.getChangelog ?? (() => getLatestChangelogEntry());
     pi.registerCommand('web-agent', {
         description: 'Open settings or manage pi-web-agent presentation config',
         handler: async (args, ctx) => {
@@ -303,6 +322,11 @@ export function registerWebAgentConfigCommands(pi, deps = {}) {
                 ].join('\n'), 'info');
                 return;
             }
+            if (action === 'changelog') {
+                const changelog = await getChangelog();
+                ctx.ui.notify(changelog ?? 'No pi-web-agent changelog entries found.', 'info');
+                return;
+            }
             if (action === 'reset') {
                 const scope = parseScopeToken(maybeScope) ?? 'project';
                 await reset(scope);
@@ -351,7 +375,7 @@ export function registerWebAgentConfigCommands(pi, deps = {}) {
                 ctx.ui.notify(`Saved ${result.scope} config`, 'info');
                 return;
             }
-            ctx.ui.notify('Use /web-agent, /web-agent show, /web-agent doctor, /web-agent reset project, or /web-agent settings', 'info');
+            ctx.ui.notify('Use /web-agent, /web-agent show, /web-agent doctor, /web-agent changelog, /web-agent reset project, or /web-agent settings', 'info');
         }
     });
 }

package/dist/extension.d.ts

@@ -1,2 +1,2 @@
-import type { ExtensionAPI } from '@mariozechner/pi-coding-agent';
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 export default function extension(pi: ExtensionAPI): void;

package/dist/extension.js

@@ -6,6 +6,7 @@ import { createResearchWorkflow } from './orchestration/index.js';
 import { loadPresentationConfigLayers } from './presentation/config-store.js';
 import { selectPresentationView } from './presentation/select-view.js';
 import { createWebExploreTool } from './tools/web-explore.js';
+import { getUpdateChangelogNotice } from './changelog-notice.js';
 async function loadWebAgentConfig(pi) {
     const store = pi.__presentationConfigStore;
     return store?.load?.() ?? loadPresentationConfigLayers();
@@ -51,6 +52,17 @@ export default function extension(pi) {
         }
         return cachedWebExplore;
     }
+    pi.on('session_start', async (_event, ctx) => {
+        try {
+            const notice = await getUpdateChangelogNotice();
+            if (notice) {
+                ctx.ui.notify(`pi-web-agent updated\n\n${notice}`, 'info');
+            }
+        }
+        catch {
+            // Never block extension startup on changelog display.
+        }
+    });
     pi.on('before_agent_start', async (event) => ({
         systemPrompt: `${event.systemPrompt}\n\n` +
             'For web research questions that require finding and comparing sources, use web_explore. ' +

package/dist/fetch/firecrawl-fetch.d.ts

@@ -1,6 +1,8 @@
+import type { FirecrawlOptions } from '../backends/config.js';
 import type { WebFetchResponse } from '../types.js';
-export declare function createFirecrawlFetcher({ baseUrl, apiKey, fetchImpl }: {
+export declare function createFirecrawlFetcher({ baseUrl, apiKey, options, fetchImpl }: {
     baseUrl: string;
     apiKey?: string;
+    options?: FirecrawlOptions;
     fetchImpl?: typeof fetch;
 }): (url: string) => Promise<WebFetchResponse>;

package/dist/fetch/firecrawl-fetch.js

@@ -4,17 +4,22 @@ function buildScrapeUrl(baseUrl) {
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
-export function createFirecrawlFetcher({ baseUrl, apiKey, fetchImpl = fetch }) {
+export function createFirecrawlFetcher({ baseUrl, apiKey, options, fetchImpl = fetch }) {
     return async function firecrawlFetch(url) {
         try {
             const headers = { 'content-type': 'application/json' };
             if (apiKey) {
                 headers.Authorization = `Bearer ${apiKey}`;
             }
+            const body = {
+                url,
+                formats: options?.formats ?? ['markdown'],
+                ...(options?.onlyMainContent !== undefined ? { onlyMainContent: options.onlyMainContent } : {})
+            };
             const response = await fetchImpl(buildScrapeUrl(baseUrl), {
                 method: 'POST',
                 headers,
-                body: JSON.stringify({ url, formats: ['markdown'] })
+                body: JSON.stringify(body)
             });
             if (!response.ok) {
                 throw new Error(`HTTP ${response.status}`);

package/dist/presentation/fetch-presentation.js

@@ -9,11 +9,14 @@ function firstExcerpt(text, maxChars = 240) {
 }
 export function buildFetchPresentation(result) {
     const wordCount = countWords(result.content?.text);
+    const fallbackPrefix = result.metadata.fallbackFrom
+        ? `${result.metadata.fallbackFrom} failed; used ${result.metadata.method} fallback. `
+        : '';
     const compact = result.status === 'ok'
-        ? `Fetched page · article extracted${wordCount ? ` · ${wordCount} words` : ''}`
+        ? `${fallbackPrefix}Fetched page · article extracted${wordCount ? ` · ${wordCount} words` : ''}`
         : result.status === 'needs_headless'
-            ? `Needs headless rendering: ${result.error?.message ?? 'Headless rendering recommended.'}`
-            : `Fetch failed: ${result.error?.message ?? 'Unknown fetch failure.'}`;
+            ? `${fallbackPrefix}Needs headless rendering: ${result.error?.message ?? 'Headless rendering recommended.'}`
+            : `${fallbackPrefix}Fetch failed: ${result.error?.message ?? 'Unknown fetch failure.'}`;
     return {
         mode: 'compact',
         views: {

package/dist/presentation/search-presentation.js

@@ -1,9 +1,12 @@
 function formatCompact(result) {
+    const fallbackPrefix = result.metadata.fallbackFrom
+        ? `${result.metadata.fallbackFrom} failed; used ${result.metadata.backend} fallback. `
+        : '';
     if (result.status === 'error') {
-        return `Search failed: ${result.error?.message ?? 'Unknown search failure.'}`;
+        return `${fallbackPrefix}Search failed: ${result.error?.message ?? 'Unknown search failure.'}`;
     }
     const suffix = result.results.length === 1 ? 'result' : 'results';
-    return `Found ${result.results.length} ${suffix}`;
+    return `${fallbackPrefix}Found ${result.results.length} ${suffix}`;
 }
 export function buildSearchPresentation(result) {
     const preview = result.results

package/dist/search/searxng.d.ts

@@ -1,6 +1,8 @@
+import type { SearxngOptions } from '../backends/config.js';
 import type { WebSearchResponse } from '../types.js';
-export declare function createSearxngSearchTool({ baseUrl, fetchImpl }: {
+export declare function createSearxngSearchTool({ baseUrl, options, fetchImpl }: {
     baseUrl: string;
+    options?: SearxngOptions;
     fetchImpl?: typeof fetch;
 }): ({ query }: {
     query: string;

package/dist/search/searxng.js

@@ -1,8 +1,14 @@
 import { buildSearchPresentation } from '../presentation/search-presentation.js';
-function buildSearchUrl(baseUrl, query) {
+function buildSearchUrl(baseUrl, query, options = {}) {
     const url = new URL('/search', baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`);
     url.searchParams.set('q', query);
     url.searchParams.set('format', 'json');
+    if (options.categories?.length)
+        url.searchParams.set('categories', options.categories.join(','));
+    if (options.language)
+        url.searchParams.set('language', options.language);
+    if (options.safesearch !== undefined)
+        url.searchParams.set('safesearch', String(options.safesearch));
     return url.toString();
 }
 function normalizeResults(response) {
@@ -19,7 +25,7 @@ function normalizeResults(response) {
         ];
     });
 }
-export function createSearxngSearchTool({ baseUrl, fetchImpl = fetch }) {
+export function createSearxngSearchTool({ baseUrl, options, fetchImpl = fetch }) {
     return async function searxngSearch({ query }) {
         const normalizedQuery = query.trim();
         if (!normalizedQuery) {
@@ -32,7 +38,7 @@ export function createSearxngSearchTool({ baseUrl, fetchImpl = fetch }) {
             return { ...result, presentation: buildSearchPresentation(result) };
         }
         try {
-            const response = await fetchImpl(buildSearchUrl(baseUrl, normalizedQuery));
+            const response = await fetchImpl(buildSearchUrl(baseUrl, normalizedQuery, options));
             if (!response.ok) {
                 throw new Error(`HTTP ${response.status}`);
             }

package/dist/types.d.ts

@@ -13,10 +13,14 @@ export type ToolError = {
 export type SearchMetadata = {
     backend: 'duckduckgo' | 'searxng';
     cacheHit: boolean;
+    fallbackFrom?: 'searxng';
+    fallbackReason?: string;
 };
 export type FetchMetadata = {
     method: 'http' | 'headless' | 'firecrawl';
     cacheHit: boolean;
+    fallbackFrom?: 'firecrawl';
+    fallbackReason?: string;
     contentType?: string;
     truncated?: boolean;
     browser?: 'configured' | 'chrome' | 'edge' | 'brave' | 'chromium';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@demigodmode/pi-web-agent",
-  "version": "0.6.0",
+  "version": "1.1.0",
   "description": "Pi package for reliable web access with explicit search, fetch, and headless boundaries.",
   "type": "module",
   "main": "./dist/extension.js",
@@ -13,7 +13,8 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "keywords": [
     "pi-package",
@@ -60,7 +61,8 @@
     "typebox": "^1.1.37"
   },
   "devDependencies": {
-    "@mariozechner/pi-coding-agent": "^0.69.0",
+    "@earendil-works/pi-coding-agent": "^0.74.0",
+    "@earendil-works/pi-tui": "^0.74.0",
     "@types/jsdom": "^21.1.7",
     "@types/node": "^24.0.0",
     "@vitest/coverage-v8": "^3.2.4",
@@ -69,6 +71,7 @@
     "vitest": "^3.2.0"
   },
   "peerDependencies": {
-    "@mariozechner/pi-coding-agent": "*"
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
   }
 }