@demigodmode/pi-web-agent 0.3.1 → 0.5.1

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

@@ -25,6 +25,12 @@ export type ResearchWorkerResult = {
     suggestedHeadlessUrl?: string;
     exhaustedBudget: boolean;
 };
+export type ResearchRunMetadata = {
+    searchPasses: number;
+    fetchedPages: number;
+    headlessAttempts: number;
+    exhaustedBudget: boolean;
+};
 export type ResearchOrchestratorDecision = {
     action: 'answer';
     rationale: string;

package/dist/orchestration/research-worker.js

@@ -1,8 +1,11 @@
+import { selectCandidates } from './candidate-selector.js';
 function classifySource(url) {
     if (url.includes('/docs/api/') || url.includes('/config/'))
         return 'official-api';
     if (url.includes('playwright.dev/docs') || url.includes('vitest.dev/guide/'))
         return 'official-docs';
+    if (url.includes('github.com/vitest-dev/vitest') && url.includes('/docs/'))
+        return 'official-docs';
     if (url.includes('learn.microsoft.com'))
         return 'official-docs';
     if (url.includes('github.com/') && url.includes('/issues/'))
@@ -91,7 +94,11 @@ export function createResearchWorker({ search, fetchPage }) {
                     exhaustedBudget: false
                 };
             }
-            const candidates = searchResult.results.slice(0, maxFetches);
+            const candidates = selectCandidates({
+                results: searchResult.results,
+                seenUrls: new Set(evidence.map((item) => item.url)),
+                maxCandidates: maxFetches
+            });
             for (const candidate of candidates) {
                 const fetched = await fetchPage({ url: candidate.url });
                 if (fetched.status === 'ok') {

package/dist/orchestration/stop-decider.d.ts

@@ -0,0 +1,19 @@
+import type { ResearchEvidence } from './research-types.js';
+export type ResearchStepDecision = {
+    action: 'answer';
+} | {
+    action: 'answer-with-caveat';
+} | {
+    action: 'search-again';
+} | {
+    action: 'headless';
+    url: string;
+};
+export declare function decideNextResearchStep({ evidence, suggestedHeadlessUrls, passIndex, maxPasses, headlessAttempts, maxHeadlessAttempts }: {
+    evidence: ResearchEvidence[];
+    suggestedHeadlessUrls: string[];
+    passIndex: number;
+    maxPasses: number;
+    headlessAttempts: number;
+    maxHeadlessAttempts: number;
+}): ResearchStepDecision;

package/dist/orchestration/stop-decider.js

@@ -0,0 +1,14 @@
+import { hasOfficialEvidence, strongEvidenceCount } from './evidence-ranker.js';
+export function decideNextResearchStep({ evidence, suggestedHeadlessUrls, passIndex, maxPasses, headlessAttempts, maxHeadlessAttempts }) {
+    if (strongEvidenceCount(evidence) >= 2 && hasOfficialEvidence(evidence)) {
+        return { action: 'answer' };
+    }
+    const headlessUrl = suggestedHeadlessUrls.find((url) => !url.includes('npmjs.com/package/'));
+    if (headlessUrl && headlessAttempts < maxHeadlessAttempts) {
+        return { action: 'headless', url: headlessUrl };
+    }
+    if (passIndex + 1 < maxPasses) {
+        return { action: 'search-again' };
+    }
+    return { action: 'answer-with-caveat' };
+}

package/dist/presentation/explore-presentation.js

@@ -1,3 +1,10 @@
+function internalReaderLabel(method) {
+    if (method === 'headless')
+        return 'web_fetch_headless';
+    if (method === 'http')
+        return 'web_fetch';
+    return 'web_explore';
+}
 export function buildExplorePresentation(result) {
     if (result.status === 'error') {
         return {
@@ -7,13 +14,26 @@ export function buildExplorePresentation(result) {
             }
         };
     }
-    const preview = result.findings.map((finding) => `- ${finding}`).join('\n');
+    const internalSummary = result.metadata
+        ? `Internal research: web_search ×${result.metadata.searchPasses}, web_fetch ×${result.metadata.fetchedPages}, web_fetch_headless ×${result.metadata.headlessAttempts}`
+        : undefined;
+    const hasEvidence = result.findings.length > 0 || result.sources.length > 0;
+    const evidenceLines = hasEvidence
+        ? result.findings.map((finding, index) => `- [${internalReaderLabel(result.sources[index]?.method)}] ${finding}`)
+        : ['No usable evidence found.'];
+    const preview = [
+        ...evidenceLines,
+        internalSummary ? `\n${internalSummary}` : undefined
+    ]
+        .filter((line) => line !== undefined)
+        .join('\n');
     const verbose = [
         'Findings',
-        ...result.findings.map((finding) => `- ${finding}`),
+        ...evidenceLines,
         '',
         'Sources',
-        ...result.sources.map((source) => `- ${source.title}: ${source.url}`),
+        ...result.sources.map((source) => `- [${internalReaderLabel(source.method)}] ${source.title}: ${source.url}`),
+        internalSummary ? `\nInternal tools\n${internalSummary}` : undefined,
         result.caveat ? `\nCaveat\n${result.caveat}` : undefined
     ]
         .filter((line) => line !== undefined)
@@ -21,7 +41,9 @@ export function buildExplorePresentation(result) {
     return {
         mode: 'compact',
         views: {
-            compact: `Reviewed ${result.sources.length} sources · synthesized answer with ${result.findings.length} findings`,
+            compact: hasEvidence
+                ? `Reviewed ${result.sources.length} sources · synthesized answer with ${result.findings.length} findings`
+                : 'No usable evidence found',
             preview,
             verbose
         },

package/dist/tools/web-explore.d.ts

@@ -1,4 +1,5 @@
 import type { ResearchEvidence } from '../orchestration/research-types.js';
+import type { WebExploreResponse } from '../types.js';
 export declare function createWebExploreTool({ explore }?: {
     explore?: {
         run: (input: {
@@ -9,6 +10,7 @@ export declare function createWebExploreTool({ explore }?: {
             };
             evidence: ResearchEvidence[];
             workerPass: unknown;
+            metadata?: WebExploreResponse['metadata'];
         }>;
     } | ((input: {
         query: string;
@@ -18,6 +20,7 @@ export declare function createWebExploreTool({ explore }?: {
         };
         evidence: ResearchEvidence[];
         workerPass: unknown;
+        metadata?: WebExploreResponse['metadata'];
     }>);
 }): ({ query }: {
     query: string;
@@ -28,7 +31,14 @@ export declare function createWebExploreTool({ explore }?: {
     sources: Array<{
         title: string;
         url: string;
+        method?: "http" | "headless";
     }>;
     caveat?: string;
+    metadata?: {
+        searchPasses: number;
+        fetchedPages: number;
+        headlessAttempts: number;
+        exhaustedBudget: boolean;
+    };
     error?: import("../types.js").ToolError;
 }>;

package/dist/tools/web-explore.js

@@ -1,18 +1,6 @@
 import { createResearchWorkflow } from '../orchestration/index.js';
+import { synthesizeAnswer } from '../orchestration/answer-synthesizer.js';
 import { buildExplorePresentation } from '../presentation/explore-presentation.js';
-function findingFromEvidence(evidence, index) {
-    if (evidence.summary.includes('Use channel')) {
-        return 'Use channel for branded Chrome or Edge when possible.';
-    }
-    if (evidence.summary.includes('use at your own risk') || evidence.summary.includes('risky')) {
-        return 'Treat executablePath as a fallback because Playwright documents it as use-at-your-own-risk.';
-    }
-    if (evidence.summary.includes('coverage.provider to v8') ||
-        evidence.summary.includes('@vitest/coverage-v8')) {
-        return 'Vitest coverage docs say to set coverage.provider to v8 and install @vitest/coverage-v8.';
-    }
-    return evidence.summary || `Finding ${index + 1}`;
-}
 export function createWebExploreTool({ explore = createResearchWorkflow() } = {}) {
     const runExplore = typeof explore === 'function' ? explore : explore.run.bind(explore);
     return async function webExplore({ query }) {
@@ -30,19 +18,21 @@ export function createWebExploreTool({ explore = createResearchWorkflow() } = {}
             };
         }
         const result = await runExplore({ query: normalizedQuery });
-        const findings = result.evidence.slice(0, 5).map(findingFromEvidence);
         const sources = result.evidence.slice(0, 4).map((item) => ({
             title: item.title,
-            url: item.url
+            url: item.url,
+            method: item.method
         }));
-        const caveat = result.decision.action === 'answer'
-            ? undefined
-            : 'Evidence is partial, so this answer is based on the strongest source found so far.';
+        const synthesized = synthesizeAnswer({
+            evidence: result.evidence,
+            partial: result.decision.action !== 'answer'
+        });
         const shaped = {
             status: 'ok',
-            findings,
+            findings: synthesized.findings,
             sources,
-            caveat
+            caveat: synthesized.caveat,
+            metadata: result.metadata
         };
         return {
             ...shaped,

package/dist/types.d.ts

@@ -19,7 +19,7 @@ export type FetchMetadata = {
     cacheHit: boolean;
     contentType?: string;
     truncated?: boolean;
-    browser?: 'configured' | 'chrome' | 'edge';
+    browser?: 'configured' | 'chrome' | 'edge' | 'brave' | 'chromium';
     navigationMs?: number;
 };
 export type ExtractedContent = {
@@ -56,8 +56,15 @@ export type WebExploreResponse = {
     sources: Array<{
         title: string;
         url: string;
+        method?: 'http' | 'headless';
     }>;
     caveat?: string;
+    metadata?: {
+        searchPasses: number;
+        fetchedPages: number;
+        headlessAttempts: number;
+        exhaustedBudget: boolean;
+    };
     presentation?: PresentationEnvelope;
     error?: ToolError;
 };

package/package.json

@@ -1,75 +1,74 @@
-{
-  "name": "@demigodmode/pi-web-agent",
-  "version": "0.3.1",
-  "description": "Pi package for reliable web access with explicit search, fetch, and headless boundaries.",
-  "type": "module",
-  "main": "./dist/extension.js",
-  "types": "./dist/extension.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/extension.d.ts",
-      "import": "./dist/extension.js"
-    }
-  },
-  "files": [
-    "dist",
-    "README.md"
-  ],
-  "keywords": [
-    "pi-package",
-    "pi",
-    "extension",
-    "web-search",
-    "web-fetch"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/demigodmode/pi-web-agent.git"
-  },
-  "homepage": "https://github.com/demigodmode/pi-web-agent#readme",
-  "bugs": {
-    "url": "https://github.com/demigodmode/pi-web-agent/issues"
-  },
-  "license": "AGPL-3.0-only",
-  "publishConfig": {
-    "access": "public"
-  },
-  "scripts": {
-    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.build.json",
-    "build:dev": "tsc -p tsconfig.json",
-    "test": "vitest run --coverage",
-    "test:watch": "vitest",
-    "lint": "tsc -p tsconfig.json --noEmit",
-    "docs:dev": "vitepress dev docs",
-    "docs:build": "vitepress build docs",
-    "docs:preview": "vitepress preview docs",
-    "eval:live": "npm run build:dev && node dist/scripts/live-web-eval.js",
-    "release:dry-run": "node scripts/release.mjs --dry-run",
-    "release": "node scripts/release.mjs"
-  },
-  "pi": {
-    "extensions": [
-      "./dist/extension.js"
-    ]
-  },
-  "dependencies": {
-    "@mozilla/readability": "^0.6.0",
-    "cheerio": "^1.1.0",
-    "jsdom": "^26.0.0",
-    "playwright-core": "^1.54.0"
-  },
-  "devDependencies": {
-    "@mariozechner/pi-coding-agent": "^0.67.2",
-    "@sinclair/typebox": "^0.34.41",
-    "@types/jsdom": "^21.1.7",
-    "@types/node": "^24.0.0",
-    "@vitest/coverage-v8": "^3.2.4",
-    "typescript": "^5.8.0",
-    "vitepress": "^1.6.4",
-    "vitest": "^3.2.0"
-  },
-  "peerDependencies": {
-    "@mariozechner/pi-coding-agent": "*",
-    "@sinclair/typebox": "*"
-  }
-}
+{
+  "name": "@demigodmode/pi-web-agent",
+  "version": "0.5.1",
+  "description": "Pi package for reliable web access with explicit search, fetch, and headless boundaries.",
+  "type": "module",
+  "main": "./dist/extension.js",
+  "types": "./dist/extension.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/extension.d.ts",
+      "import": "./dist/extension.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "pi-package",
+    "pi",
+    "extension",
+    "web-search",
+    "web-fetch"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/demigodmode/pi-web-agent.git"
+  },
+  "homepage": "https://github.com/demigodmode/pi-web-agent#readme",
+  "bugs": {
+    "url": "https://github.com/demigodmode/pi-web-agent/issues"
+  },
+  "license": "AGPL-3.0-only",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.build.json",
+    "build:dev": "tsc -p tsconfig.json",
+    "test": "vitest run --coverage",
+    "test:watch": "vitest",
+    "lint": "tsc -p tsconfig.json --noEmit",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs",
+    "eval:live": "npm run build:dev && node dist/scripts/live-web-eval.js",
+    "release:dry-run": "node scripts/release.mjs --dry-run",
+    "release": "node scripts/release.mjs"
+  },
+  "pi": {
+    "extensions": [
+      "./dist/extension.js"
+    ]
+  },
+  "dependencies": {
+    "@mozilla/readability": "^0.6.0",
+    "cheerio": "^1.1.0",
+    "jsdom": "^26.0.0",
+    "playwright-core": "^1.54.0",
+    "typebox": "^1.1.37"
+  },
+  "devDependencies": {
+    "@mariozechner/pi-coding-agent": "^0.69.0",
+    "@types/jsdom": "^21.1.7",
+    "@types/node": "^24.0.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "typescript": "^5.8.0",
+    "vitepress": "^1.6.4",
+    "vitest": "^3.2.0"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*"
+  }
+}