@demigodmode/pi-web-agent 0.2.2 → 0.4.0

package/dist/presentation/search-presentation.js

@@ -0,0 +1,30 @@
+function formatCompact(result) {
+    if (result.status === 'error') {
+        return `Search failed: ${result.error?.message ?? 'Unknown search failure.'}`;
+    }
+    const suffix = result.results.length === 1 ? 'result' : 'results';
+    return `Found ${result.results.length} ${suffix}`;
+}
+export function buildSearchPresentation(result) {
+    const preview = result.results
+        .slice(0, 3)
+        .map((item, index) => `${index + 1}. ${item.title}`)
+        .join('\n');
+    const verbose = result.results
+        .slice(0, 5)
+        .map((item, index) => `${index + 1}. ${item.title}\n   ${item.url}\n   ${item.snippet}`)
+        .join('\n');
+    return {
+        mode: 'compact',
+        views: {
+            compact: formatCompact(result),
+            preview: preview || undefined,
+            verbose: verbose || undefined
+        },
+        metrics: {
+            resultCount: result.results.length,
+            cacheHit: result.metadata.cacheHit
+        },
+        sources: result.results.map((item) => ({ title: item.title, url: item.url }))
+    };
+}

package/dist/presentation/select-view.d.ts

@@ -0,0 +1,2 @@
+import type { PresentationEnvelope, PresentationMode } from './types.js';
+export declare function selectPresentationView(envelope: PresentationEnvelope | undefined, requestedMode: PresentationMode): string | undefined;

package/dist/presentation/select-view.js

@@ -0,0 +1,12 @@
+export function selectPresentationView(envelope, requestedMode) {
+    if (!envelope) {
+        return undefined;
+    }
+    if (requestedMode === 'preview' && envelope.views.preview) {
+        return envelope.views.preview;
+    }
+    if (requestedMode === 'verbose' && envelope.views.verbose) {
+        return envelope.views.verbose;
+    }
+    return envelope.views.compact;
+}

package/dist/presentation/types.d.ts

@@ -0,0 +1,50 @@
+export declare const PRESENTATION_MODES: readonly ["compact", "preview", "verbose"];
+export type PresentationMode = (typeof PRESENTATION_MODES)[number];
+export type PresentationViews = {
+    compact: string;
+    preview?: string;
+    verbose?: string;
+};
+export type PresentationMetrics = {
+    durationMs?: number;
+    resultCount?: number;
+    sourceCount?: number;
+    wordCount?: number;
+    statusCode?: number;
+    cacheHit?: boolean;
+    truncated?: boolean;
+};
+export type PresentationSource = {
+    title: string;
+    url: string;
+    domain?: string;
+};
+export type PresentationEnvelope = {
+    mode: PresentationMode;
+    views: PresentationViews;
+    metrics?: PresentationMetrics;
+    sources?: PresentationSource[];
+    debug?: Record<string, unknown>;
+};
+export type PresentationToolName = 'web_search' | 'web_fetch' | 'web_fetch_headless' | 'web_explore';
+export type PresentationScope = 'global' | 'project';
+export type PresentationToolOverrideMode = PresentationMode;
+export type PresentationToolConfig = {
+    mode: PresentationToolOverrideMode;
+};
+export type PresentationConfig = {
+    defaultMode: PresentationMode;
+    tools: Partial<Record<PresentationToolName, PresentationToolConfig>>;
+};
+export type PresentationConfigOverride = {
+    defaultMode?: PresentationMode;
+    tools: Partial<Record<PresentationToolName, PresentationToolConfig>>;
+};
+export type PresentationConfigFile = {
+    presentation?: {
+        defaultMode?: unknown;
+        tools?: Partial<Record<PresentationToolName, {
+            mode?: unknown;
+        }>>;
+    };
+};

package/dist/presentation/types.js

@@ -0,0 +1 @@
+export const PRESENTATION_MODES = ['compact', 'preview', 'verbose'];

package/dist/search/duckduckgo.d.ts

@@ -1,4 +1,9 @@
 import type { SearchResult } from '../types.js';
+export type ParsedDuckDuckGoResults = {
+    results: SearchResult[];
+    noResults: boolean;
+    hasResultContainers: boolean;
+};
 export declare function buildSearchUrl(query: string): string;
 export declare function fetchDuckDuckGoHtml(query: string): Promise<string>;
-export declare function parseDuckDuckGoResults(html: string): SearchResult[];
+export declare function parseDuckDuckGoResults(html: string): ParsedDuckDuckGoResults;

package/dist/search/duckduckgo.js

@@ -30,7 +30,8 @@ export async function fetchDuckDuckGoHtml(query) {
 }
 export function parseDuckDuckGoResults(html) {
     const $ = cheerio.load(html);
-    return $('.result')
+    const resultContainers = $('.result');
+    const results = resultContainers
         .map((_, element) => {
         const title = $(element).find('.result__a').first().text().trim();
         const url = normalizeDuckDuckGoUrl($(element).find('.result__a').first().attr('href')?.trim() ?? '');
@@ -39,4 +40,13 @@ export function parseDuckDuckGoResults(html) {
     })
         .get()
         .filter((value) => value !== null);
+    const text = $.text().toLowerCase();
+    const noResults = text.includes('no results found') ||
+        text.includes('no more results') ||
+        text.includes('did not match any documents');
+    return {
+        results,
+        noResults,
+        hasResultContainers: resultContainers.length > 0
+    };
 }

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,27 +20,25 @@ export declare function createWebExploreTool({ explore }?: {
         };
         evidence: ResearchEvidence[];
         workerPass: unknown;
+        metadata?: WebExploreResponse['metadata'];
     }>);
 }): ({ query }: {
     query: string;
 }) => Promise<{
-    status: "error";
-    findings: never[];
-    sources: never[];
-    error: {
-        code: string;
-        message: string;
-    };
-    caveat?: undefined;
-    text?: undefined;
-} | {
-    status: "ok";
+    presentation: import("../presentation/types.js").PresentationEnvelope;
+    status: "ok" | "error";
     findings: string[];
-    sources: {
+    sources: Array<{
         title: string;
         url: string;
-    }[];
-    caveat: string | undefined;
-    text: string;
-    error?: undefined;
+        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,50 +1,42 @@
 import { createResearchWorkflow } from '../orchestration/index.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}`;
-}
-function formatExploreText({ findings, sources, caveat }) {
-    const findingLines = findings.map((finding) => `- ${finding}`).join('\n');
-    const sourceLines = sources.map((source) => `- ${source.title}: ${source.url}`).join('\n');
-    const caveatBlock = caveat ? `\n\nCaveat\n${caveat}` : '';
-    return `Findings\n${findingLines}\n\nSources\n${sourceLines}${caveatBlock}`;
-}
+import { synthesizeAnswer } from '../orchestration/answer-synthesizer.js';
+import { buildExplorePresentation } from '../presentation/explore-presentation.js';
 export function createWebExploreTool({ explore = createResearchWorkflow() } = {}) {
     const runExplore = typeof explore === 'function' ? explore : explore.run.bind(explore);
     return async function webExplore({ query }) {
         const normalizedQuery = query.trim();
         if (!normalizedQuery) {
-            return {
+            const result = {
                 status: 'error',
                 findings: [],
                 sources: [],
                 error: { code: 'INVALID_QUERY', message: 'Query must not be empty.' }
             };
+            return {
+                ...result,
+                presentation: buildExplorePresentation(result)
+            };
         }
         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.';
-        return {
+        const synthesized = synthesizeAnswer({
+            evidence: result.evidence,
+            partial: result.decision.action !== 'answer'
+        });
+        const shaped = {
             status: 'ok',
-            findings,
+            findings: synthesized.findings,
             sources,
-            caveat,
-            text: formatExploreText({ findings, sources, caveat })
+            caveat: synthesized.caveat,
+            metadata: result.metadata
+        };
+        return {
+            ...shaped,
+            presentation: buildExplorePresentation(shaped)
         };
     };
 }

package/dist/tools/web-fetch-headless.js

@@ -1,14 +1,23 @@
 import { headlessFetch } from '../fetch/headless-fetch.js';
+import { buildFetchPresentation } from '../presentation/fetch-presentation.js';
 export function createWebFetchHeadlessTool({ fetchPage = headlessFetch } = {}) {
     return async function webFetchHeadless({ url }) {
         if (!/^https?:\/\//.test(url)) {
-            return {
+            const result = {
                 status: 'unsupported',
                 url,
                 metadata: { method: 'headless', cacheHit: false },
                 error: { code: 'UNSUPPORTED_URL', message: 'Only http and https URLs are supported.' }
             };
+            return {
+                ...result,
+                presentation: buildFetchPresentation(result)
+            };
         }
-        return fetchPage(url);
+        const result = await fetchPage(url);
+        return {
+            ...result,
+            presentation: buildFetchPresentation(result)
+        };
     };
 }

package/dist/tools/web-fetch.js

@@ -1,14 +1,23 @@
 import { createHttpFetcher } from '../fetch/http-fetch.js';
+import { buildFetchPresentation } from '../presentation/fetch-presentation.js';
 export function createWebFetchTool({ fetchPage = createHttpFetcher() } = {}) {
     return async function webFetch({ url }) {
         if (!/^https?:\/\//.test(url)) {
-            return {
+            const result = {
                 status: 'unsupported',
                 url,
                 metadata: { method: 'http', cacheHit: false },
                 error: { code: 'UNSUPPORTED_URL', message: 'Only http and https URLs are supported.' }
             };
+            return {
+                ...result,
+                presentation: buildFetchPresentation(result)
+            };
         }
-        return fetchPage(url);
+        const result = await fetchPage(url);
+        return {
+            ...result,
+            presentation: buildFetchPresentation(result)
+        };
     };
 }

package/dist/tools/web-search.js

@@ -1,43 +1,130 @@
 import { createCacheKey, createTtlCache } from '../cache/ttl-cache.js';
+import { buildSearchPresentation } from '../presentation/search-presentation.js';
 import { fetchDuckDuckGoHtml, parseDuckDuckGoResults } from '../search/duckduckgo.js';
+function classifySearchFailure(error) {
+    const rawMessage = error instanceof Error ? error.message : 'Unknown search failure.';
+    const normalized = rawMessage.toLowerCase();
+    if (normalized.includes('blocked') ||
+        normalized.includes('rate limit') ||
+        normalized.includes('rate-limit') ||
+        normalized.includes('403') ||
+        normalized.includes('429') ||
+        normalized.includes('captcha') ||
+        normalized.includes('challenge')) {
+        return {
+            code: 'BLOCKED',
+            message: 'DuckDuckGo search appears to be blocked or rate limited.'
+        };
+    }
+    return {
+        code: 'FETCH_FAILED',
+        message: `DuckDuckGo search request failed: ${rawMessage}`
+    };
+}
+function htmlLooksBlocked(html) {
+    const normalized = html.toLowerCase();
+    return (normalized.includes('captcha') ||
+        normalized.includes('challenge') ||
+        normalized.includes('verify you are human') ||
+        normalized.includes('are you a robot') ||
+        normalized.includes('unusual traffic'));
+}
 export function createWebSearchTool({ searchHtml = fetchDuckDuckGoHtml, cache = createTtlCache({ ttlMs: 30_000 }) } = {}) {
     return async function webSearch({ query }) {
         const normalizedQuery = query.trim();
         if (!normalizedQuery) {
-            return {
+            const result = {
                 status: 'error',
                 results: [],
                 metadata: { backend: 'duckduckgo', cacheHit: false },
                 error: { code: 'INVALID_QUERY', message: 'Query must not be empty.' }
             };
+            return {
+                ...result,
+                presentation: buildSearchPresentation(result)
+            };
         }
         const cacheKey = createCacheKey(['web_search', normalizedQuery]);
         const cached = cache.get(cacheKey);
         if (cached) {
-            return {
+            const result = {
                 ...cached,
                 metadata: { ...cached.metadata, cacheHit: true }
             };
+            return {
+                ...result,
+                presentation: buildSearchPresentation(result)
+            };
         }
         try {
             const html = await searchHtml(normalizedQuery);
+            const parsed = parseDuckDuckGoResults(html);
+            if (parsed.results.length > 0) {
+                const result = {
+                    status: 'ok',
+                    results: parsed.results,
+                    metadata: { backend: 'duckduckgo', cacheHit: false }
+                };
+                cache.set(cacheKey, result);
+                return {
+                    ...result,
+                    presentation: buildSearchPresentation(result)
+                };
+            }
+            if (parsed.noResults) {
+                const result = {
+                    status: 'error',
+                    results: [],
+                    metadata: { backend: 'duckduckgo', cacheHit: false },
+                    error: {
+                        code: 'NO_RESULTS',
+                        message: 'DuckDuckGo returned no usable results for this query.'
+                    }
+                };
+                return {
+                    ...result,
+                    presentation: buildSearchPresentation(result)
+                };
+            }
+            if (htmlLooksBlocked(html)) {
+                const result = {
+                    status: 'error',
+                    results: [],
+                    metadata: { backend: 'duckduckgo', cacheHit: false },
+                    error: {
+                        code: 'BLOCKED',
+                        message: 'DuckDuckGo search appears to be blocked or rate limited.'
+                    }
+                };
+                return {
+                    ...result,
+                    presentation: buildSearchPresentation(result)
+                };
+            }
             const result = {
-                status: 'ok',
-                results: parseDuckDuckGoResults(html),
-                metadata: { backend: 'duckduckgo', cacheHit: false }
+                status: 'error',
+                results: [],
+                metadata: { backend: 'duckduckgo', cacheHit: false },
+                error: {
+                    code: 'PARSE_FAILED',
+                    message: 'DuckDuckGo returned a page, but it did not match the expected results format.'
+                }
+            };
+            return {
+                ...result,
+                presentation: buildSearchPresentation(result)
             };
-            cache.set(cacheKey, result);
-            return result;
         }
         catch (error) {
-            return {
+            const result = {
                 status: 'error',
                 results: [],
                 metadata: { backend: 'duckduckgo', cacheHit: false },
-                error: {
-                    code: 'SEARCH_FAILED',
-                    message: error instanceof Error ? error.message : 'Unknown search failure.'
-                }
+                error: classifySearchFailure(error)
+            };
+            return {
+                ...result,
+                presentation: buildSearchPresentation(result)
             };
         }
     };

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import type { PresentationEnvelope } from './presentation/types.js';
 export declare const TOOL_STATUSES: readonly ["ok", "needs_headless", "blocked", "unsupported", "error"];
 export type ToolStatus = (typeof TOOL_STATUSES)[number];
 export type SearchResult = {
@@ -30,6 +31,7 @@ export type WebSearchResponse = {
     status: 'ok' | 'error';
     results: SearchResult[];
     metadata: SearchMetadata;
+    presentation?: PresentationEnvelope;
     error?: ToolError;
 };
 export type WebFetchResponse = {
@@ -37,6 +39,7 @@ export type WebFetchResponse = {
     url: string;
     content?: ExtractedContent;
     metadata: FetchMetadata;
+    presentation?: PresentationEnvelope;
     error?: ToolError;
 };
 export type WebFetchHeadlessResponse = {
@@ -44,5 +47,24 @@ export type WebFetchHeadlessResponse = {
     url: string;
     content?: ExtractedContent;
     metadata: FetchMetadata;
+    presentation?: PresentationEnvelope;
+    error?: ToolError;
+};
+export type WebExploreResponse = {
+    status: 'ok' | 'error';
+    findings: string[];
+    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,75 @@
-{
-  "name": "@demigodmode/pi-web-agent",
-  "version": "0.2.2",
-  "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.4.0",
+  "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": "*"
+  }
+}

package/dist/scripts/live-web-eval.d.ts

@@ -1 +0,0 @@
-export {};