@demigodmode/pi-web-agent 0.3.1 → 0.4.0

package/README.md

@@ -1,119 +1,119 @@
-# 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
+```
+
+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 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.js

@@ -2,12 +2,7 @@ import { getSettingsListTheme } from '@mariozechner/pi-coding-agent';
 import { Container, 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'
-];
+const PRESENTATION_TOOL_NAMES = ['web_explore'];
 function parseScopeToken(token) {
     return token === 'global' || token === 'project' ? token : undefined;
 }

package/dist/extension.js

@@ -4,9 +4,6 @@ import { DEFAULT_PRESENTATION_CONFIG, resolvePresentationMode } from './presenta
 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/orchestration/answer-synthesizer.d.ts

@@ -0,0 +1,8 @@
+import type { ResearchEvidence } from './research-types.js';
+export declare function synthesizeAnswer({ evidence, partial }: {
+    evidence: ResearchEvidence[];
+    partial: boolean;
+}): {
+    findings: string[];
+    caveat: string | undefined;
+};

package/dist/orchestration/answer-synthesizer.js

@@ -0,0 +1,17 @@
+function normalizeSummary(summary) {
+    return summary.replace(/\s+/g, ' ').trim();
+}
+export function synthesizeAnswer({ evidence, partial }) {
+    const findings = evidence.slice(0, 5).map((item) => {
+        const summary = normalizeSummary(item.summary);
+        return item.sourceKind === 'community' || item.sourceKind === 'issue-thread'
+            ? `Community/practical context: ${summary}`
+            : summary;
+    });
+    return {
+        findings,
+        caveat: partial
+            ? 'Evidence is partial, so this answer is based on the strongest source found within the bounded research budget.'
+            : undefined
+    };
+}

package/dist/orchestration/candidate-selector.d.ts

@@ -0,0 +1,6 @@
+import type { SearchResult } from '../types.js';
+export declare function selectCandidates({ results, seenUrls, maxCandidates }: {
+    results: SearchResult[];
+    seenUrls: Set<string>;
+    maxCandidates: number;
+}): SearchResult[];

package/dist/orchestration/candidate-selector.js

@@ -0,0 +1,24 @@
+function candidateScore(result) {
+    const url = result.url.toLowerCase();
+    if (url.includes('playwright.dev/docs') || url.includes('vitest.dev/guide') || url.includes('learn.microsoft.com'))
+        return 0;
+    if (url.includes('github.com/') && (url.includes('/issues/') || url.includes('/discussions/')))
+        return 1;
+    if (url.includes('github.com/'))
+        return 2;
+    if (url.includes('npmjs.com/package/'))
+        return 4;
+    return 3;
+}
+export function selectCandidates({ results, seenUrls, maxCandidates }) {
+    const deduped = new Map();
+    for (const result of results) {
+        if (seenUrls.has(result.url))
+            continue;
+        if (!deduped.has(result.url))
+            deduped.set(result.url, result);
+    }
+    return [...deduped.values()]
+        .sort((left, right) => candidateScore(left) - candidateScore(right))
+        .slice(0, maxCandidates);
+}

package/dist/orchestration/evidence-ranker.d.ts

@@ -0,0 +1,4 @@
+import type { ResearchEvidence } from './research-types.js';
+export declare function rankEvidence(evidence: ResearchEvidence[]): ResearchEvidence[];
+export declare function hasOfficialEvidence(evidence: ResearchEvidence[]): boolean;
+export declare function strongEvidenceCount(evidence: ResearchEvidence[]): number;

package/dist/orchestration/evidence-ranker.js

@@ -0,0 +1,36 @@
+function sourceRank(sourceKind) {
+    switch (sourceKind) {
+        case 'official-docs':
+            return 0;
+        case 'official-api':
+            return 1;
+        case 'official-discussion':
+            return 2;
+        case 'issue-thread':
+            return 3;
+        case 'community':
+            return 4;
+        case 'package-page':
+            return 5;
+        default:
+            return 6;
+    }
+}
+export function rankEvidence(evidence) {
+    const bestByUrl = new Map();
+    for (const item of evidence) {
+        const current = bestByUrl.get(item.url);
+        if (!current || sourceRank(item.sourceKind) < sourceRank(current.sourceKind)) {
+            bestByUrl.set(item.url, item);
+        }
+    }
+    return [...bestByUrl.values()].sort((left, right) => sourceRank(left.sourceKind) - sourceRank(right.sourceKind));
+}
+export function hasOfficialEvidence(evidence) {
+    return evidence.some((item) => item.sourceKind === 'official-docs' || item.sourceKind === 'official-api');
+}
+export function strongEvidenceCount(evidence) {
+    return evidence.filter((item) => item.sourceKind === 'official-docs' ||
+        item.sourceKind === 'official-api' ||
+        item.sourceKind === 'official-discussion').length;
+}

package/dist/orchestration/index.d.ts

@@ -13,29 +13,14 @@ export declare function createResearchWorkflow({ search, fetchPage, headlessFetc
     run({ query }: {
         query: string;
     }): Promise<{
-        decision: {
-            action: "answer";
-            rationale: string;
-            approvedEvidence: import("./research-types.js").ResearchEvidence[];
-        };
-        evidence: import("./research-types.js").ResearchEvidence[];
-        workerPass: import("./research-types.js").ResearchWorkerResult;
-    } | {
-        decision: {
-            action: "escalate-headless";
-            rationale: string;
-            url: string;
-            approvedEvidence: import("./research-types.js").ResearchEvidence[];
-        };
+        decision: import("./research-types.js").ResearchOrchestratorDecision;
         evidence: import("./research-types.js").ResearchEvidence[];
         workerPass: import("./research-types.js").ResearchWorkerResult;
-    } | {
-        decision: {
-            action: "research-again";
-            rationale: string;
-            followupQuery: string;
+        metadata: {
+            searchPasses: number;
+            fetchedPages: number;
+            headlessAttempts: number;
+            exhaustedBudget: boolean;
         };
-        evidence: import("./research-types.js").ResearchEvidence[];
-        workerPass: import("./research-types.js").ResearchWorkerResult;
     }>;
 };

package/dist/orchestration/query-planner.d.ts

@@ -0,0 +1,7 @@
+export type QueryPlanInput = {
+    originalQuery: string;
+    passIndex: number;
+    previousQueries: string[];
+    gaps: string[];
+};
+export declare function planSearchQueries(input: QueryPlanInput): string[];

package/dist/orchestration/query-planner.js

@@ -0,0 +1,37 @@
+function normalizeWhitespace(value) {
+    return value.replace(/\s+/g, ' ').trim();
+}
+function extractImportantWords(query) {
+    return normalizeWhitespace(query)
+        .replace(/\b(find|current|tell|me|how|to|the|and|with|for|in|a|an)\b/gi, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+function officialSiteQuery(query) {
+    const lower = query.toLowerCase();
+    const terms = extractImportantWords(query);
+    if (lower.includes('vitest'))
+        return `site:vitest.dev ${terms}`;
+    if (lower.includes('playwright'))
+        return `site:playwright.dev ${terms}`;
+    if (lower.includes('microsoft edge') || lower.includes('edge'))
+        return `site:learn.microsoft.com ${terms}`;
+    return `${terms} official docs`;
+}
+function implementationQuery(query) {
+    return `site:github.com ${extractImportantWords(query)}`;
+}
+export function planSearchQueries(input) {
+    const planned = input.passIndex === 0
+        ? [input.originalQuery]
+        : [
+            officialSiteQuery(input.originalQuery),
+            implementationQuery(input.originalQuery),
+            `${extractImportantWords(input.originalQuery)} discussion`
+        ];
+    const previous = new Set(input.previousQueries.map(normalizeWhitespace));
+    return planned
+        .map(normalizeWhitespace)
+        .filter((query) => query && !previous.has(query))
+        .slice(0, 3);
+}

package/dist/orchestration/research-orchestrator.d.ts

@@ -1,5 +1,5 @@
 import type { WebFetchHeadlessResponse } from '../types.js';
-import type { ResearchEvidence, ResearchWorkerResult } from './research-types.js';
+import type { ResearchEvidence, ResearchOrchestratorDecision, ResearchWorkerResult } from './research-types.js';
 export declare function createResearchOrchestrator({ worker, headlessFetch }: {
     worker: {
         run: (input: {
@@ -15,29 +15,14 @@ export declare function createResearchOrchestrator({ worker, headlessFetch }: {
     run({ query }: {
         query: string;
     }): Promise<{
-        decision: {
-            action: "answer";
-            rationale: string;
-            approvedEvidence: ResearchEvidence[];
-        };
-        evidence: ResearchEvidence[];
-        workerPass: ResearchWorkerResult;
-    } | {
-        decision: {
-            action: "escalate-headless";
-            rationale: string;
-            url: string;
-            approvedEvidence: ResearchEvidence[];
-        };
+        decision: ResearchOrchestratorDecision;
         evidence: ResearchEvidence[];
         workerPass: ResearchWorkerResult;
-    } | {
-        decision: {
-            action: "research-again";
-            rationale: string;
-            followupQuery: string;
+        metadata: {
+            searchPasses: number;
+            fetchedPages: number;
+            headlessAttempts: number;
+            exhaustedBudget: boolean;
         };
-        evidence: ResearchEvidence[];
-        workerPass: ResearchWorkerResult;
     }>;
 };