@demigodmode/pi-web-agent 0.3.1 → 0.5.1

package/README.md

@@ -1,119 +1,124 @@
-# pi-web-agent
-
-[![CI](https://github.com/demigodmode/pi-web-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/demigodmode/pi-web-agent/actions/workflows/ci.yml)
-[![npm version](https://img.shields.io/npm/v/@demigodmode/pi-web-agent)](https://www.npmjs.com/package/@demigodmode/pi-web-agent)
-[![Docs](https://img.shields.io/badge/docs-github%20pages-blue)](https://demigodmode.github.io/pi-web-agent/)
-
-`@demigodmode/pi-web-agent` is a Pi package for web access.
-
-The whole point is keeping the boundaries straight:
-
-- `web_search` is for discovery
-- `web_fetch` is for plain HTTP reads
-- `web_fetch_headless` is the explicit browser path
-- `web_explore` is the bounded research path
-
-That sounds obvious, but a lot of agent tooling gets fuzzy right there. This package is meant to be stricter about what it actually did and more willing to say when a read was not good enough to trust.
-
-## Install
-
-```bash
-pi install npm:@demigodmode/pi-web-agent
-```
-
-Later on, update installed packages with:
-
-```bash
-pi update
-```
-
-## Docs
-
-Docs site:
-
-- https://demigodmode.github.io/pi-web-agent/
-
-Work on the docs locally:
-
-```bash
-npm run docs:dev
-```
-
-Build the docs:
-
-```bash
-npm run docs:build
-```
-
-## Presentation modes
-
-`pi-web-agent` renders web tool output in one visible mode at a time:
-
-- `compact` — short summary, default everywhere
-- `preview` — slightly richer bounded view
-- `verbose` — fuller bounded view
-
-## Settings
-
-Primary UI:
-
-```text
-/web-agent settings
-```
-
-Helper commands:
-
-```text
-/web-agent show
-/web-agent reset project
-/web-agent reset global
-/web-agent mode preview
-/web-agent mode web_search verbose
-/web-agent mode web_search inherit
-```
-
-Config files:
-
-```text
-Global:  ~/.pi/agent/extensions/pi-web-agent/config.json
-Project: .pi/extensions/pi-web-agent/config.json
-```
-
-Precedence:
-
-- built-in defaults
-- global config
-- project config
-
-Project config overrides global config.
-
-Example:
-
-```json
-{
-  "presentation": {
-    "defaultMode": "compact",
-    "tools": {
-      "web_search": { "mode": "preview" },
-      "web_explore": { "mode": "verbose" }
-    }
-  }
-}
-```
-
-## Local development
-
-```bash
-npm install
-npm test
-npm run lint
-npm run build
-```
-
-For local Pi work, this repo includes `.pi/extensions/pi-web-agent.ts`.
-
-If Pi is already running, use `/reload` after changes.
-
-## License
-
-AGPL-3.0-only. See `LICENSE`.
+# pi-web-agent
+
+[![CI](https://github.com/demigodmode/pi-web-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/demigodmode/pi-web-agent/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@demigodmode/pi-web-agent)](https://www.npmjs.com/package/@demigodmode/pi-web-agent)
+[![Docs](https://img.shields.io/badge/docs-github%20pages-blue)](https://demigodmode.github.io/pi-web-agent/)
+
+`@demigodmode/pi-web-agent` is a Pi package for web access.
+
+Most agent web tools blur search, fetch, browser rendering, and research into one vague thing. `pi-web-agent` exposes one public research tool, `web_explore`, and keeps search/fetch/headless work inside that bounded workflow.
+
+The point is keeping the model-facing boundary simple: ask `web_explore` to research a question, and it handles discovery, HTTP reads, targeted browser rendering, source ranking, and caveats internally.
+
+That sounds obvious, but a lot of agent tooling gets fuzzy right there. This package is meant to be stricter about what it actually did and more willing to say when a read was not good enough to trust.
+
+## Install
+
+```bash
+pi install npm:@demigodmode/pi-web-agent
+```
+
+After installing, reload or restart Pi. Run `/web-agent` for the action menu, or `/web-agent doctor` to check whether the package loaded cleanly and whether headless rendering can find a browser.
+
+Headless rendering currently requires a detectable Chromium-family browser: Chrome, Chromium, Edge, or Brave. Firefox/Safari-only systems can still use search and plain HTTP reads, but browser-rendered fallback pages need a supported Chromium-family browser for now.
+
+Later on, update installed packages with:
+
+```bash
+pi update
+```
+
+## Docs
+
+Docs site:
+
+- https://demigodmode.github.io/pi-web-agent/
+
+Work on the docs locally:
+
+```bash
+npm run docs:dev
+```
+
+Build the docs:
+
+```bash
+npm run docs:build
+```
+
+## Presentation modes
+
+`pi-web-agent` renders web tool output in one visible mode at a time:
+
+- `compact` — short summary, default everywhere
+- `preview` — slightly richer bounded view
+- `verbose` — fuller bounded view
+
+See the `v0.3.0` release notes for a before/after of the transcript cleanup:
+
+- https://github.com/demigodmode/pi-web-agent/releases/tag/v0.3.0
+
+## Settings
+
+Primary UI:
+
+```text
+/web-agent settings
+```
+
+Helper commands:
+
+```text
+/web-agent doctor
+/web-agent show
+/web-agent reset project
+/web-agent reset global
+/web-agent mode preview
+/web-agent mode web_explore verbose
+/web-agent mode web_explore inherit
+```
+
+Config files:
+
+```text
+Global:  ~/.pi/agent/extensions/pi-web-agent/config.json
+Project: .pi/extensions/pi-web-agent/config.json
+```
+
+Precedence:
+
+- built-in defaults
+- global config
+- project config
+
+Project config overrides global config.
+
+Example:
+
+```json
+{
+  "presentation": {
+    "defaultMode": "compact",
+    "tools": {
+      "web_explore": { "mode": "verbose" }
+    }
+  }
+}
+```
+
+## Local development
+
+```bash
+npm install
+npm test
+npm run lint
+npm run build
+```
+
+For local Pi work, this repo includes `.pi/extensions/pi-web-agent.ts`.
+
+If Pi is already running, use `/reload` after changes.
+
+## License
+
+AGPL-3.0-only. See `LICENSE`.

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

@@ -1,10 +1,18 @@
 import { type ExtensionAPI } from '@mariozechner/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';
 type CommandDeps = {
     load?: () => ReturnType<typeof loadPresentationConfigLayers>;
     save?: (scope: PresentationScope, config: PresentationConfigOverride) => Promise<void>;
     reset?: (scope: PresentationScope) => Promise<void>;
+    resolveBrowser?: () => Promise<BrowserResolutionResult>;
+    runtime?: {
+        nodeVersion: string;
+        platform: string;
+        arch: string;
+    };
+    checkTypebox?: () => Promise<boolean>;
 };
 export type SettingsDraftState = {
     scope: PresentationScope;

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

@@ -1,13 +1,9 @@
-import { getSettingsListTheme } from '@mariozechner/pi-coding-agent';
-import { Container, SettingsList, Text } from '@mariozechner/pi-tui';
+import { DynamicBorder, getSettingsListTheme } from '@mariozechner/pi-coding-agent';
+import { Container, SelectList, SettingsList, Text } from '@mariozechner/pi-tui';
 import { DEFAULT_PRESENTATION_CONFIG, mergePresentationConfigLayers, resolvePresentationMode } from '../presentation/config.js';
 import { loadPresentationConfigLayers, resetPresentationConfigScope, savePresentationConfigScope } from '../presentation/config-store.js';
-const PRESENTATION_TOOL_NAMES = [
-    'web_search',
-    'web_fetch',
-    'web_fetch_headless',
-    'web_explore'
-];
+import { resolveBrowserExecutable } from '../fetch/browser-resolution.js';
+const PRESENTATION_TOOL_NAMES = ['web_explore'];
 function parseScopeToken(token) {
     return token === 'global' || token === 'project' ? token : undefined;
 }
@@ -17,6 +13,15 @@ function clonePresentationConfig(config) {
         tools: { ...config.tools }
     };
 }
+async function defaultCheckTypebox() {
+    try {
+        await import('typebox');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 function formatConfigSummary(config) {
     const lines = [`defaultMode: ${config.defaultMode}`];
     for (const toolName of PRESENTATION_TOOL_NAMES) {
@@ -142,6 +147,40 @@ export function handleSettingsShortcut(data) {
     }
     return undefined;
 }
+async function openActionMenu(ctx) {
+    return ctx.ui.custom((tui, theme, _kb, done) => {
+        const container = new Container();
+        const items = [
+            { value: 'settings', label: 'Settings', description: 'Edit presentation modes' },
+            { value: 'show', label: 'Show config', description: 'Print effective config paths and modes' },
+            { value: 'doctor', label: 'Doctor', description: 'Check runtime dependencies and browser detection' },
+            { value: 'reset-project', label: 'Reset project config', description: 'Delete project-level overrides' },
+            { value: 'reset-global', label: 'Reset global config', description: 'Delete global overrides' }
+        ];
+        container.addChild(new DynamicBorder((text) => theme.fg('accent', text)));
+        container.addChild(new Text(theme.fg('accent', theme.bold('pi-web-agent')), 1, 0));
+        const list = new SelectList(items, Math.min(items.length, 8), {
+            selectedPrefix: (text) => theme.fg('accent', text),
+            selectedText: (text) => theme.fg('accent', text),
+            description: (text) => theme.fg('muted', text),
+            scrollInfo: (text) => theme.fg('dim', text),
+            noMatch: (text) => theme.fg('warning', text)
+        });
+        list.onSelect = (item) => done(item.value);
+        list.onCancel = () => done(undefined);
+        container.addChild(list);
+        container.addChild(new Text(theme.fg('dim', '↑↓ navigate • enter select • esc cancel'), 1, 0));
+        container.addChild(new DynamicBorder((text) => theme.fg('accent', text)));
+        return {
+            render: (width) => container.render(width),
+            invalidate: () => container.invalidate(),
+            handleInput: (data) => {
+                list.handleInput?.(data);
+                tui.requestRender?.();
+            }
+        };
+    });
+}
 async function openSettingsUi(ctx, loaded, initialScope) {
     return ctx.ui.custom((_tui, theme, _kb, done) => {
         let state = createSettingsDraftState(loaded, initialScope);
@@ -187,10 +226,51 @@ export function registerWebAgentConfigCommands(pi, deps = {}) {
     const load = deps.load ?? (() => loadPresentationConfigLayers());
     const save = deps.save ?? ((scope, config) => savePresentationConfigScope({}, scope, config));
     const reset = deps.reset ?? ((scope) => resetPresentationConfigScope({}, scope));
+    const resolveBrowser = deps.resolveBrowser ?? (() => resolveBrowserExecutable({}));
+    const runtime = deps.runtime ?? {
+        nodeVersion: process.version,
+        platform: process.platform,
+        arch: process.arch
+    };
+    const checkTypebox = deps.checkTypebox ?? defaultCheckTypebox;
     pi.registerCommand('web-agent', {
         description: 'Open settings or manage pi-web-agent presentation config',
         handler: async (args, ctx) => {
-            const [action, maybeScope] = (args ?? '').trim().split(/\s+/).filter(Boolean);
+            let [action, maybeScope] = (args ?? '').trim().split(/\s+/).filter(Boolean);
+            if (!action) {
+                const selectedAction = await openActionMenu(ctx);
+                if (!selectedAction)
+                    return;
+                if (selectedAction === 'reset-project') {
+                    action = 'reset';
+                    maybeScope = 'project';
+                }
+                else if (selectedAction === 'reset-global') {
+                    action = 'reset';
+                    maybeScope = 'global';
+                }
+                else {
+                    action = selectedAction;
+                }
+            }
+            if (action === 'doctor') {
+                const [typeboxOk, browser] = await Promise.all([checkTypebox(), resolveBrowser()]);
+                const lines = [
+                    'pi-web-agent: loaded',
+                    `runtime: node ${runtime.nodeVersion} ${runtime.platform} ${runtime.arch}`,
+                    `typebox: ${typeboxOk ? 'ok' : 'missing'}`
+                ];
+                if (browser.ok) {
+                    lines.push(`browser: ${browser.browser} ${browser.executablePath}`);
+                }
+                else {
+                    lines.push(`browser: missing (${browser.error.code})`);
+                    lines.push(browser.error.message);
+                    lines.push('Install Chrome, Chromium, Edge, or Brave and run /web-agent doctor again.');
+                }
+                ctx.ui.notify(lines.join('\n'), 'info');
+                return;
+            }
             if (action === 'show') {
                 const loaded = await load();
                 ctx.ui.notify([
@@ -248,7 +328,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 reset project, or /web-agent settings', 'info');
+            ctx.ui.notify('Use /web-agent, /web-agent show, /web-agent doctor, /web-agent reset project, or /web-agent settings', 'info');
         }
     });
 }

package/dist/extension.js

@@ -1,12 +1,9 @@
-import { Type } from '@sinclair/typebox';
+import { Type } from 'typebox';
 import { registerWebAgentConfigCommands } from './commands/web-agent-config.js';
 import { DEFAULT_PRESENTATION_CONFIG, resolvePresentationMode } from './presentation/config.js';
 import { loadPresentationConfigLayers } from './presentation/config-store.js';
 import { selectPresentationView } from './presentation/select-view.js';
 import { createWebExploreTool } from './tools/web-explore.js';
-import { createWebFetchTool } from './tools/web-fetch.js';
-import { createWebFetchHeadlessTool } from './tools/web-fetch-headless.js';
-import { createWebSearchTool } from './tools/web-search.js';
 async function getEffectivePresentationConfig(pi) {
     const store = pi.__presentationConfigStore;
     try {
@@ -24,165 +21,23 @@ async function renderToolText(pi, toolName, details) {
 }
 export default function extension(pi) {
     registerWebAgentConfigCommands(pi);
-    const webSearch = createWebSearchTool();
-    const webFetch = createWebFetchTool();
-    const webFetchHeadless = createWebFetchHeadlessTool();
-    const webExplore = createWebExploreTool();
-    let webExploreUsedInCurrentFlow = false;
-    const postWebExploreGuardError = {
-        code: 'POST_WEB_EXPLORE_GUARD',
-        message: 'web_explore already ran for this research task. Only use low-level web tools if there is a specific unresolved gap.'
-    };
-    async function guardSearchResponse() {
-        const result = {
-            status: 'error',
-            results: [],
-            metadata: {
-                backend: 'duckduckgo',
-                cacheHit: false
-            },
-            error: postWebExploreGuardError,
-            presentation: {
-                mode: 'compact',
-                views: {
-                    compact: `Search failed: ${postWebExploreGuardError.message}`
-                }
-            }
-        };
-        return {
-            content: [{ type: 'text', text: await renderToolText(pi, 'web_search', result) }],
-            details: result,
-            isError: true
-        };
-    }
-    async function guardFetchResponse(url) {
-        const result = {
-            status: 'error',
-            url,
-            metadata: {
-                method: 'http',
-                cacheHit: false
-            },
-            error: postWebExploreGuardError,
-            presentation: {
-                mode: 'compact',
-                views: {
-                    compact: `Fetch failed: ${postWebExploreGuardError.message}`
-                }
-            }
-        };
-        return {
-            content: [{ type: 'text', text: await renderToolText(pi, 'web_fetch', result) }],
-            details: result,
-            isError: true
-        };
-    }
-    async function guardHeadlessResponse(url) {
-        const result = {
-            status: 'error',
-            url,
-            metadata: {
-                method: 'headless',
-                cacheHit: false
-            },
-            error: postWebExploreGuardError,
-            presentation: {
-                mode: 'compact',
-                views: {
-                    compact: `Fetch failed: ${postWebExploreGuardError.message}`
-                }
-            }
-        };
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: await renderToolText(pi, 'web_fetch_headless', result)
-                }
-            ],
-            details: result,
-            isError: true
-        };
-    }
-    pi.on('before_agent_start', async (event) => {
-        webExploreUsedInCurrentFlow = false;
-        return {
-            systemPrompt: `${event.systemPrompt}\n\n` +
-                'For web research questions that require finding and comparing multiple sources, prefer web_explore. ' +
-                'Use web_search, web_fetch, and web_fetch_headless for direct/manual operations like explicit search calls, specific URL reads, or debugging. ' +
-                'After using web_explore, only call low-level web tools if there is a specific unresolved gap. ' +
-                'Do not keep searching or fetching just for extra confirmation.'
-        };
-    });
-    pi.registerTool({
-        name: 'web_search',
-        label: 'Web Search',
-        description: 'Direct search tool for manual discovery of links and snippets. Use for explicit search requests or when the user wants raw search results. Prefer web_explore for broader research questions.',
-        parameters: Type.Object({
-            query: Type.String({ description: 'Search query.' })
-        }),
-        async execute(_toolCallId, params) {
-            if (webExploreUsedInCurrentFlow) {
-                return guardSearchResponse();
-            }
-            const result = await webSearch({ query: params.query });
-            return {
-                content: [{ type: 'text', text: await renderToolText(pi, 'web_search', result) }],
-                details: result,
-                isError: result.status === 'error'
-            };
-        }
-    });
-    pi.registerTool({
-        name: 'web_fetch',
-        label: 'Web Fetch',
-        description: 'Direct HTTP page fetch for a specific URL. Use when the user wants one page read directly. Prefer web_explore for broader research across multiple sources.',
-        parameters: Type.Object({
-            url: Type.String({ description: 'HTTP or HTTPS URL to fetch.' })
-        }),
-        async execute(_toolCallId, params) {
-            if (webExploreUsedInCurrentFlow) {
-                return guardFetchResponse(params.url);
-            }
-            const result = await webFetch({ url: params.url });
-            return {
-                content: [{ type: 'text', text: await renderToolText(pi, 'web_fetch', result) }],
-                details: result,
-                isError: result.status === 'error'
-            };
-        }
-    });
-    pi.registerTool({
-        name: 'web_fetch_headless',
-        label: 'Web Fetch Headless',
-        description: 'Direct headless page fetch for a specific URL when browser rendering is explicitly needed. Prefer web_explore for research tasks; it decides headless escalation internally.',
-        parameters: Type.Object({
-            url: Type.String({ description: 'HTTP or HTTPS URL to fetch in headless mode.' })
-        }),
-        async execute(_toolCallId, params) {
-            if (webExploreUsedInCurrentFlow) {
-                return guardHeadlessResponse(params.url);
-            }
-            const result = await webFetchHeadless({ url: params.url });
-            return {
-                content: [{ type: 'text', text: await renderToolText(pi, 'web_fetch_headless', result) }],
-                details: result,
-                isError: result.status === 'error'
-            };
-        }
-    });
+    const webExplore = pi.__webExploreTool ??
+        createWebExploreTool();
+    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. ' +
+            'web_explore handles search, fetch, source ranking, and headless escalation internally. ' +
+            'If more web evidence is needed after web_explore, call web_explore again with a narrower query; do not use shell/network commands such as curl, Invoke-WebRequest, npm view/search/pack, or direct HTTP URLs for web research.'
+    }));
     pi.registerTool({
         name: 'web_explore',
         label: 'Web Explore',
-        description: 'Research a web question using bounded search/fetch passes, source ranking, and targeted headless escalation. Prefer this for multi-source web research, current docs/discussion lookups, and recommendation summaries. Use this instead of chaining low-level web tools for the same research task.',
+        description: 'Research a web question using bounded search/fetch passes, source ranking, and targeted headless escalation. Use this for web research, current docs/discussion lookups, and recommendation summaries.',
         parameters: Type.Object({
             query: Type.String({ description: 'Web research question to explore.' })
         }),
         async execute(_toolCallId, params) {
             const result = await webExplore({ query: params.query });
-            if (result.status === 'ok') {
-                webExploreUsedInCurrentFlow = true;
-            }
             return {
                 content: [
                     {

package/dist/fetch/browser-resolution.d.ts

@@ -1,7 +1,9 @@
+type SupportedPlatform = NodeJS.Platform | string;
+type BrowserName = 'configured' | 'chrome' | 'edge' | 'brave' | 'chromium';
 export type BrowserResolutionResult = {
     ok: true;
     executablePath: string;
-    browser: 'configured' | 'chrome' | 'edge';
+    browser: BrowserName;
 } | {
     ok: false;
     error: {
@@ -9,7 +11,10 @@ export type BrowserResolutionResult = {
         message: string;
     };
 };
-export declare function resolveBrowserExecutable({ configuredPath, fileExists }: {
+export declare function resolveBrowserExecutable({ configuredPath, platform, env, fileExists }: {
     configuredPath?: string;
+    platform?: SupportedPlatform;
+    env?: NodeJS.ProcessEnv | Record<string, string | undefined>;
     fileExists?: (path: string) => Promise<boolean>;
 }): Promise<BrowserResolutionResult>;
+export {};